Documentation Roadmap¶
"Documentation is a love letter that you write to your future self." — Damian Conway
This roadmap is about engineering documentation as a craft — the docs an engineer writes and maintains as part of building software: docstrings, READMEs, API references, ADRs, design docs, runbooks, and the tooling that keeps them all alive. It is the how-to-document-your-work discipline, not a writing career.
Not what you're looking for? - The technical-writing career (content strategy, marketing, distribution) → Soft-Skills → Technical Writer. - Measuring doc quality (coverage, freshness metrics, gates) → Quality Engineering → Documentation Quality. - In-code comments specifically → Clean Code → Comments.
Why a Dedicated Roadmap¶
Code says what it does; documentation says why it exists, how to use it, and what we decided and rejected. That second layer is what lets a team scale past the people who wrote the code. Yet documentation is the most consistently neglected engineering skill — not because engineers can't write, but because nobody taught them what to document, where it belongs, and how to keep it from rotting. This roadmap is that missing curriculum.
| Roadmap | Question it answers |
|---|---|
| Clean Code → Comments | When should code explain itself in a comment? |
| Soft-Skills → Technical Writer | How do I build a career and audience as a writer? |
| Documentation (this) | What does an engineer document, where, and how do I keep it alive? |
Sections¶
| # | Topic | Focus |
|---|---|---|
| 01 | Why & What to Document | The documentation spectrum, audiences, the cost of too much vs too little |
| 02 | Code Comments & Docstrings | Intent over mechanics, API docstrings, doc generators (cross-links Clean Code → Comments) |
| 03 | READMEs & Onboarding | The README as a front door; getting-started, setup, contribution guides |
| 04 | API & Reference Docs | Reference vs guides, OpenAPI, generated docs, examples that run |
| 05 | Architecture Decision Records | Capturing why — ADR format, when to write one, superseding decisions |
| 06 | Design Docs & RFCs | Pre-build alignment, the design-doc template, the RFC review process |
| 07 | Runbooks & Ops Docs | On-call runbooks, incident playbooks, operational knowledge that saves the 3 a.m. page |
| 08 | Diagrams as Code | Mermaid, C4, PlantUML — version-controlled, reviewable diagrams |
| 09 | Changelogs & Release Notes | Keep a Changelog, semver, human vs machine notes, conventional commits |
| 10 | Docs as Code & Tooling | Docs in the repo, linting, link-checking, versioned docs sites, CI for docs |
| 11 | Keeping Docs Alive | Fighting doc rot, single source of truth, docs that live next to the code they describe |
Scope & Deduplication¶
| Looks similar to | But here we cover | Lives in |
|---|---|---|
05-architecture-decision-records-adrs | ADRs as an engineering practice | (replaces the former Clean Code ch. 24 stub, now removed) |
02-code-comments-and-docstrings | docstrings & doc generation | inline comment style → Clean Code → Comments |
04-api-and-reference-documentation | reference docs as a craft | API-doc tooling → Backend → API Documentation Tools |
| whole roadmap | the engineer's documentation practice | the writing career → Soft-Skills → Technical Writer |
Status¶
Content-complete. All 11 topics are written following the Code Craft file convention — five levels each (junior · middle · senior · professional · interview). All content in English.