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

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

## Opening

* 2012 the year of the mayan 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, qucikstart and how-to)
* Website (the first impression - what does this do, why would i need it)
* REAMDE (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, ...) -> Seperate 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 fundemental 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 gonna 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 documetnation

* Project docs helps users according to their needs -> Low question to answer latency
* Contributor docs enables contributions in a predictable manner -> Don't leave "when will this be reviewed/mered" questions open
* Website proves why anyone should invest time in this projects?
* All documetnation 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 conent in intro (concept) and getting started (practice)
  * Hierarchie includes concepts, key features and guides/tutorials

## Q&A

* Every last wednesday in the month is a cncf echnical writers meetin (cncf slack -> techdocs)