---
title: "Towards Great Documentation: Behind a CNCF-Led Docs Audit"
weight: 4
tags:
  - docs
  - dx
---

{{% button href="https://youtu.be/a9bjo4poYGY" style="warning" icon="video" %}}Watch talk on YouTube{{% /button %}}

A talk about the backstage documentation audit and what makes a good documentation.

## Opening

* 2012 the year of the Maya calendar and the mainstream success of memes
* The classic meme RTFM -> Classic manuals were pretty long
* 2024: Manuals have become documentation (hopefully with better contents)

## What gets us to good documentation

### What is documentation

* Docs (the raw descriptions, quick-start and how-to)
* Website (the first impression - what does this do, why would I need it)
* README (the GitHub way of website + docs)
* CONTRIBUTING (Is this a one-man show)
* Issues
* Meta docs (how do we orchestrate things)

### Project documentation

* Who needs this documentation?
  * New users -> Optimize for minimum context
  * Experienced users
  * User roles (Admins, end users, ...) -> Separate into different pages (Get started based in your role)
* What do we need to enable with this documentation?
  * Prove value fast -> Why this project?
  * Educate on fundamental aspects
  * Showcase features/uses cases
  * Hands-on enablement -> Tutorials, guides, step-by-step

### Contributor documentation

* Communication channels have to be clearly marked
* Documented scheduled contributor meetings
* Getting started guides for new contributors
* Project governance
  * Who is going to own it?
  * What will happen to my PR?
  * Who maintains features?

### Website

* Single source for all pages (one repo that includes landing, docs, API and so on) -> Easier to contribute
* Usability (especially on mobile)
* Social proof and case studies -> Develop trust
* SEO (actually get found) and analytics (detect how documentation is used and where people leave)
* Plan website maintenance

### What is great documentation

* Project docs help users according to their needs -> Low question to answer latency
* Contributor docs enables contributions predictably -> Don't leave "when will this be reviewed/merged" questions open
* Website proves why anyone should invest time in these projects?
* All documentation is connected and up to date

## General best practices

* Insular pages: One page per topic, preferably short
* Include API reference
* Searchable
* Plan for versioning early on (the right framework is important)
* Plan for localization

## Examples

* OpenTelemetry: Split by role (dev, ops)
* Prometheus:
  * New user content in intro (concept) and getting started (practice)
  * Hierarchies includes concepts, key features and guides/tutorials

## Q&A

* Every last Wednesday in the month is a CNCF technical writers meeting (CNCF slack -> `#techdocs`)