2.6 KiB
2.6 KiB
| title | weight | tags | ||
|---|---|---|---|---|
| Towards Great Documentation: Behind a CNCF-Led Docs Audit | 4 |
|
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)