2.7 Documentation¶

Overview and motivation¶

Documentation is the written knowledge that lets people use, operate, and change software without having to piece together understanding from the code alone. It comes in many genres: how to get started, how to accomplish a task, how a system is structured, how to respond to an incident, what an API accepts and returns. Each one serves a different reader with a different need. Good documentation is not optional. It is the difference between knowledge that scales across a large organization and knowledge that lives in just a few people's heads.

For large teams, documentation is your best defense against key-person risk (the danger when critical knowledge sits with only one or a few people) and your fastest way to onboard newcomers. When hundreds of engineers depend on systems they didn't build, and people join, move, and leave all the time, the organization can only function if knowledge is written down and easy to find. Undocumented systems turn fragile: only their authors can safely change them, and when those authors leave, the organization loses the ability to maintain its own software. That's one of the most common and expensive failures at scale.

Enterprise and government contexts raise the stakes further. Systems live a long time, so your documentation has to serve maintainers years, even decades, after the original team is gone. Regulatory and audit regimes often mandate specific documents as evidence of control: architecture records, runbooks (step-by-step operational and incident-response procedures), and decision logs. Public-sector systems handed between vendors rely entirely on documentation to carry knowledge across contract boundaries. And yet documentation is famously prone to rot, so the real challenge is keeping it accurate as the software changes.

Key principles¶

• Write for a specific reader with a specific need; different documentation types serve different purposes.
• Keep documentation close to the code and treat it as code (docs-as-code).
• Accuracy beats completeness; a small amount of trustworthy documentation beats a large amount that is wrong.
• Generate what can be generated; do not hand-maintain what a tool can produce from the source of truth.
• Fight documentation rot actively; stale docs are worse than none because they mislead.
• Make documentation discoverable; unfindable knowledge is effectively absent.
• Record decisions and their rationale, not just the current state.

Recommendations¶

Adopt docs-as-code¶

Keep documentation in version control right alongside the code it describes, write it in plain-text markup, and review it through the same pull-request process. That keeps it versioned, reviewable, and close to the code, so you can update both together. Publish it through an automated pipeline so the latest version is always available. Treating docs as code brings the same discipline that keeps code trustworthy: review, history, and automation.

Structure content with the Diátaxis framework¶

Organize documentation into four distinct types, because mixing them serves no reader well: tutorials (learning-oriented, for newcomers), how-to guides (task-oriented, for a specific goal), reference (information-oriented, precise and complete), and explanation (understanding-oriented, the why and the context). Keep these separate and everything gets easier to write, navigate, and maintain, because each page has one clear job and one clear audience.

Maintain the essential operational documents¶

Give every repository a clear README as its front door: what it is, how to build and run it, and where to go next. Write runbooks for operational tasks and incident response, so anyone on call can act, not just the experts. Keep architecture documentation that explains the system's structure and key components. And provide onboarding documentation that gets a new engineer productive quickly. These are the documents you miss most when they aren't there.

Generate API docs and changelogs from the source of truth¶

Generate your API reference documentation from the machine-readable contract or code annotations, so it can't drift from the actual interface. Keep a changelog, ideally generated from structured commits or release notes, so consumers can see what changed between versions. Automating these takes the most rot-prone hand-maintained documentation off your plate and keeps it trustworthy.

Record architecture decisions¶

Capture significant architectural and design decisions as lightweight, dated records that state the context, the decision, and its consequences. These decision records preserve the rationale that would otherwise be lost, so future maintainers can see why the system is the way it is instead of second-guessing it or repeating old mistakes. They pay off especially over the long lifespans of enterprise and government systems.

Fight documentation rot deliberately¶

Treat stale documentation as a defect. Update the docs as part of the same change that alters behavior, and make that a review expectation. Assign ownership so every important document has someone responsible for it. Review high-value documentation for accuracy now and then, prune what's obsolete, and remove or clearly flag anything you no longer trust. The documentation that rots least is living documentation: generated or tested against the system itself.

Invest in knowledge management and discoverability¶

Make documentation findable through good search, clear navigation, and a known home, so people can locate what they need without having to ask someone. Don't let it fragment across too many disconnected wikis and tools. And capture tacit knowledge, the informal understanding that lives in chat threads and people's heads, into durable, findable form before it slips away.

Trade-offs: pros and cons¶

The central trade-off is effort versus accuracy and durability. The cheapest documentation to write, a quick wiki page, is also the most prone to rot and fragmentation. The most durable documentation, generated from the source or reviewed as code, costs more discipline up front but stays trustworthy. A good rule of thumb: generate what you can, keep the rest close to the code and reviewed like code, and save labor-intensive hand-written explanation for the rationale that only humans can provide.

Examples¶

Startup. A five-person startup writes a real README for each service and a short runbook for the one deploy-and-recover procedure everyone dreads, so a 2 a.m. outage does not depend on waking the single founder who knows the system. They generate API docs from the contract instead of hand-writing them, and jot a few dated notes explaining why they chose their database and their auth approach. It stays lightweight, but it means the sixth and seventh hires onboard from documents rather than by interrupting everyone.

Enterprise. A large software company keeps all its documentation in the same repositories as its code, written in markup and reviewed in pull requests right alongside the changes they describe. API references are generated from service contracts, so they never drift. Changelogs are generated from structured commits, and architecture decision records preserve the reasoning behind major choices. A published documentation site builds automatically on every merge. New engineers get productive fast because onboarding guides and runbooks are current and findable, and on-call engineers lean on runbooks instead of paging the original authors.

Government. A national agency inherits a system from a departing contractor, depending entirely on documentation to carry knowledge across the contract boundary. Because the previous vendor maintained architecture documentation, runbooks, and decision records as mandated deliverables, the new team can operate and modify the system without the original authors. Where documentation was thin, the agency faces costly reverse-engineering. That experience drives a new policy: documentation is a contractual deliverable, reviewed for accuracy rather than treated as an afterthought, and runbooks must let any authorized operator respond to incidents.

Business case: motivations, ROI, and TCO¶

Documentation pays you back in shorter onboarding time, less key-person risk, faster incident response, and a lower cost of change over a system's life. New engineers reaching productivity in days rather than weeks, on-call staff resolving incidents from a runbook instead of escalating, maintainers changing a system confidently years after it was built: these are large, recurring savings that compound across a big organization and a long system lifespan.

What does documentation cost? Authoring and maintenance effort. What does not documenting cost? You pay continuously: in slow onboarding, repeated questions, key-person bottlenecks, slower incident recovery, and, at the extreme, systems no one can safely change, forcing expensive rewrites or reverse-engineering. In vendor-transition and audit scenarios, missing documentation can carry direct contractual and compliance costs. To make the case to leadership, put numbers on onboarding time, incident-response time, and how much critical knowledge sits in individual heads. Then frame docs-as-code and generation as ways to get durable documentation without a matching maintenance burden. And stress that inaccurate documentation is a liability, so the investment has to include keeping it current.

Anti-patterns and pitfalls¶

• Stale documentation presented as current: misleads readers and destroys trust in all documentation.
• The write-once wiki: pages created and never updated, silently drifting from reality.
• Documentation fragmentation: knowledge scattered across many tools and wikis so nothing can be found.
• Mixing documentation types: tutorials, reference, and explanation jumbled on one page, serving no reader well.
• Hand-maintaining generatable content: manually written API docs that inevitably diverge from the actual interface.
• Tribal knowledge: critical understanding kept only in people's heads and chat history, lost when they leave.
• Documentation as an afterthought: written at the end, if at all, rather than alongside the change.
• No ownership: documents with no responsible owner rot because updating them is nobody's job.

Maturity model¶

• Level 1 (Initial): Documentation is sparse, scattered, and stale; knowledge lives in people's heads.
• Level 2 (Repeatable): Key documents exist (READMEs, some runbooks) but are inconsistently maintained and hard to find.
• Level 3 (Defined): Docs-as-code with a clear structure, generated API docs and changelogs, decision records, and update expectations in review.
• Level 4 (Optimizing): Documentation is living and largely generated or tested against the system, owned, discoverable, measured for accuracy, and actively pruned to fight rot.

Ideas for discussion¶

• Which documentation, if it vanished tomorrow, would hurt your organization most, and does it currently exist and stay current?
• How do you make updating documentation a natural part of changing code rather than a separate chore?
• Where can you replace hand-written documentation with generated documentation tied to the source of truth?
• How do you measure whether your documentation is accurate and used, not just present?
• How should AI assistants change how you write, maintain, and search documentation, and where might they introduce plausible-but-wrong content?
• How do you capture tacit knowledge before the people who hold it leave?

Key takeaways¶

• Treat documentation as code: versioned, reviewed, close to the source, and published automatically.
• Structure content by reader need using tutorials, how-to guides, reference, and explanation.
• Maintain the high-value essentials: READMEs, runbooks, architecture docs, onboarding, and decision records.
• Generate API docs and changelogs so they cannot drift from the source of truth.
• Fight rot with ownership, review expectations, and pruning; inaccurate documentation is worse than none.

References and further reading¶

• Daniele Procida, Diátaxis documentation framework
• Andrew Etter, Modern Technical Writing
• Anne Gentle, Docs Like Code
• Google, Developer Documentation Style Guide and Season of Docs guidance (as reference exemplars)
• Michael Nygard, Documenting Architecture Decisions (architecture decision records)
• Andrew Hunt and David Thomas, The Pragmatic Programmer (on knowledge and documentation)
• Keep a Changelog (as a reference convention)