Towards Great Documentation: Behind a CNCF-Led Docs Audit

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)