kubecon24/content/day3/04_towards_great_docs.md

title	weight
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 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)