2024-03-21 16:00:27 +00:00
|
|
|
---
|
|
|
|
|
title: "Towards Great Documentation: Behind a CNCF-Led Docs Audit"
|
|
|
|
|
weight: 4
|
2024-03-25 12:45:10 +00:00
|
|
|
tags:
|
|
|
|
|
- docs
|
|
|
|
|
- dx
|
2024-03-21 16:00:27 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
|
|
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)
|
2024-03-21 16:54:49 +00:00
|
|
|
* 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)
|
