85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
---
|
|
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`)
|