Chapter 10: Documentation
seg process documentation knowledge-management engineering-culture
Status: Notes complete
Overview
Documentation is one of the most neglected engineering practices. Engineers who would never ship untested code routinely ship code with no documentation, inadequate documentation, or documentation that is wrong. Chapter 10 argues that this neglect is not a character flaw but a structural problem: documentation, unlike code, provides no immediate feedback when it is absent or wrong. Code that is missing a function fails to compile; documentation that is missing a concept fails silently, only surfacing its absence when a new engineer spends three hours figuring out something that could have been explained in a paragraph.
The chapter establishes documentation as a first-class engineering artifact — something that requires ownership, review, and maintenance on the same terms as code. It examines why engineers resist writing documentation, what constitutes documentation (the answer is broader than most engineers assume), the types of documentation that serve different purposes, how to think about the audience for documentation, and the principles that distinguish good documentation from bad.
The authors are honest that documentation at Google is imperfect and that the engineering culture around documentation lags behind the culture around testing and code review. But they present the case that investing in documentation is one of the highest-leverage activities available to a team operating at scale, precisely because its benefits — reduced onboarding time, fewer repeated questions, preserved institutional knowledge — compound over time.
Core Concepts
Documentation: Any written artifact that communicates information about code, systems, or processes to a reader. This includes, but is not limited to: inline code comments, API reference documentation, design documents, tutorials, READMEs, conceptual guides, and landing pages. The authors insist on this broad definition to counter the narrow view that “documentation” means only the formal reference material written by technical writers.
Audience: The intended reader of a piece of documentation. Good documentation is written for a specific audience; documentation written for “everyone” is typically useful to no one. The audience affects vocabulary, assumed knowledge level, structure, and purpose.
Documentation debt: The accumulated backlog of missing, incorrect, or outdated documentation. Like technical debt, it is created faster than it is paid down when documentation is not treated as a first-class concern, and it compounds — outdated documentation can be worse than no documentation because it actively misleads readers.
What Qualifies as Documentation
The authors deliberately expand the definition of documentation beyond formal reference material. Documentation includes:
| Documentation Type | Examples |
|---|---|
| Inline code comments | Function doc comments, inline explanations of non-obvious logic |
| API reference documentation | Generated from doc comments; describes what each function/class/method does |
| Design documents | Pre-implementation documents describing the design of a system or feature |
| Tutorials | Step-by-step guides for completing a specific task from start to finish |
| Conceptual documentation | Explanations of how a system works and why, without task orientation |
| READMEs | Entry-point documentation for a repository or package |
| Landing pages | Navigation documents that orient readers and direct them to the right resource |
This expanded definition matters because engineers often treat inline comments as “not really documentation” and therefore don’t apply the same rigor to them that they would apply to formal documentation. The authors insist the same principles — accuracy, clarity, audience-awareness — apply to all written artifacts.
Why Engineers Resist Writing Documentation
The authors name several root causes of documentation neglect:
1. No immediate feedback loop: When code is broken, something fails — a test, a build, a deployment. When documentation is missing or wrong, nothing fails immediately. The feedback only comes when someone else needs the documentation and cannot find it or is misled by it.
2. Documentation is seen as someone else’s job: Many engineers believe technical writers exist to write documentation, and engineers exist to write code. The authors reject this division. Technical writers are editors and polish-artists; engineers are the primary authors of documentation about the systems they build.
3. Documentation becomes stale quickly: Engineers who invest time in documentation see it become inaccurate as the system evolves. This creates a learned helplessness: “Why bother? It’ll just be wrong in six months.” The authors address this directly: documentation should be treated like code — maintained and updated as the system changes.
4. Documentation writing feels unproductive: Writing documentation produces no visible artifact in the near term. The value is invisible until someone who needed the documentation encounters it. This makes it easy to deprioritize in favor of work whose output is immediately tangible.
5. Engineers don’t know what to write: A common paralysis: the engineer understands the system deeply but doesn’t know where to start or what level of detail is appropriate for someone who doesn’t. Knowing your audience is the answer to this problem.
Documentation Is Like Code
This is the chapter’s central thesis, and it has several concrete implications:
Documentation Requires Ownership
Code without an owner accumulates debt and is eventually abandoned or deleted. The same is true of documentation. Every piece of documentation should have a designated owner — someone responsible for keeping it accurate as the system evolves. At Google, documentation ownership is often co-located with code ownership: the team that owns a system also owns its documentation.
Documentation Requires Review
Just as code is reviewed before being merged, documentation should be reviewed before being published. Documentation review catches inaccuracies, unclear explanations, missing context, and audience mismatches. It also creates accountability: the reviewer shares responsibility for the documentation’s quality.
A key distinction: documentation review does not require the reviewer to be a subject-matter expert. A non-expert reviewer is often the most valuable reviewer for documentation — if they cannot understand it, neither can the audience the documentation is meant to serve.
Documentation Requires Maintenance
Documentation that is not maintained becomes misleading. Stale documentation is often worse than no documentation because it creates false confidence — a reader assumes the documentation is accurate and acts on incorrect information. Teams should treat documentation updates as part of the definition of “done” for any change that affects documented behavior.
The Parallel to Code
Code Documentation
---- -------------
Code review before merge Doc review before publish
Code owner per module Doc owner per document
Tests verify correctness Readers verify accuracy
Refactor when it grows stale Update when system changes
Delete dead code Delete deprecated docs
Knowing Your Audience
Documentation has an intended reader, and that reader shapes every decision about what to include, what to assume, and how to explain things. The authors identify three primary audience types:
Beginners
Beginners encounter a system for the first time. They do not know the vocabulary, the architecture, or the conventions. Documentation for beginners must:
- Define terms before using them
- Not assume prior knowledge of the system’s internals
- Provide working examples that can be run without modification
- Walk through tasks step by step
- Explain the “why” alongside the “what”
Tutorials are the primary documentation type for beginners.
Experienced Users / Experts
Experts already understand the system. Documentation for experts:
- Can use system-specific vocabulary without definition
- Should be organized for lookup rather than linear reading
- Should focus on completeness and accuracy over explanation
- Should include edge cases, error conditions, and nuance
API reference documentation is the primary type for experts.
Cross-Functional Audiences
Some documentation must serve readers from multiple domains — engineers, product managers, technical writers, external partners. Documentation for cross-functional audiences:
- Must define terms that are obvious within one domain but not another
- Should avoid deep technical implementation details unless relevant to all audiences
- Should use clear structural organization (headings, tables) to allow different readers to navigate to what they need
Design documents and landing pages often serve cross-functional audiences.
Documentation Types in Depth
Reference Documentation
Reference documentation is the exhaustive, accurate description of what a system does: what functions exist, what parameters they take, what they return, and what errors they can produce. Reference documentation is generated from inline doc comments and should be:
- Accurate above all else — inaccurate reference documentation is harmful
- Complete — missing a parameter or return value is a bug
- Lookup-oriented — organized so experts can find what they need quickly, not read linearly
At Google, engineers are expected to document every public API. The documentation is not optional.
Design Documents
Design documents are written before implementation and describe:
- The problem being solved
- The alternatives considered and the reasoning for choosing the selected approach
- The design of the solution at a level appropriate for peer review
- Known trade-offs and open questions
Design documents serve three purposes: they force the author to think the problem through before writing code; they allow peers to review the design before significant implementation work is committed; and they create a permanent record of the design intent that future engineers can consult.
At Google, design documents are expected for any significant new system or major change to an existing one.
Tutorials
Tutorials walk a new user through a task from start to finish in a working environment. The defining characteristic of a tutorial: the reader should be able to follow it and end up with a working result.
Good tutorials:
- Start from a known, reproducible starting state
- Include every step — assume nothing
- Provide commands or code that can be copy-pasted and run
- Verify success at each step
- Point the reader toward next steps
Bad tutorials: skip steps, contain untested commands, assume environment configuration the reader doesn’t have.
Tutorials are the hardest documentation to maintain because they must work end-to-end in a real environment, and changes to any part of the stack can break them silently.
Conceptual Documentation
Conceptual documentation explains how a system works and why it is designed the way it is — without necessarily guiding the reader to accomplish a specific task. It answers the question “what is this and how does it work?” rather than “how do I do X?”
Conceptual documentation is valuable for:
- Onboarding engineers who need to understand the whole before working on the parts
- Explaining non-obvious design decisions (the “why” behind the structure)
- Providing the mental model readers need to use reference documentation effectively
Conceptual documentation is the most commonly neglected type because it is the hardest to scope — it is easy to write too much (a full system overview the reader will never read) or too little (a brief paragraph that doesn’t provide the model the reader needs).
Landing Pages
A landing page is a navigation document. It does not contain substantial content itself; it orients the reader within a documentation space and directs them to the right resource. A good landing page:
- Explains what the documentation space covers
- Lists the main resources with brief descriptions
- Is organized to match how readers navigate (by task, by audience, or by system component)
Landing pages are often the first piece of documentation a new user sees, and they are frequently neglected. A poor landing page sends new users on a scavenger hunt; a good landing page has them reading the right documentation in minutes.
Documentation Philosophy: WHO WHAT WHEN WHERE WHY
The authors propose a framework for thinking about any documentation artifact: every piece of documentation has answers to these five questions, and the clarity of those answers determines the documentation’s quality.
| Question | What It Covers |
|---|---|
| WHO | Who is this documentation for? What is their background and expertise level? |
| WHAT | What does this document cover? What is its scope? |
| WHEN | When should a reader consult this document? At what stage of their work? |
| WHERE | Where does this document live? How does a reader find it? |
| WHY | Why does this document exist? What problem does it solve? |
Authors who cannot answer these questions clearly for their documentation are likely to write documentation that fails its intended readers. The framework is equally useful for evaluating existing documentation: if you cannot answer these questions about a document, it needs to be clarified or replaced.
Beginning, Middle, and End Structure
Good documentation follows the reader’s mental journey, not the system’s internal structure. The authors advocate for a three-part structure:
Beginning: Orient the reader. Who is this document for? What will they learn? What should they know before reading? A good beginning tells the reader immediately whether this document is for them and what they will get from it.
Middle: The substance. Deliver what was promised in the beginning. Use clear headings, examples, and progressive disclosure — start with the most common case, add complexity gradually.
End: Close the loop. Summarize what was covered. Point to next steps or related resources. A reader who finishes the document should know where to go next.
This structure mirrors good writing in any domain but is frequently absent from engineering documentation, which often dives into implementation details without orienting the reader and ends abruptly without providing closure.
Parameters of Good Documentation
The authors identify three parameters that determine documentation quality:
Accuracy: The documentation correctly describes the system. Inaccurate documentation is worse than no documentation — it misleads readers and erodes trust in all documentation. Accuracy requires maintenance; it degrades over time as the system evolves.
Clarity: The documentation can be understood by its intended audience without significant effort. Clarity depends entirely on knowing the audience — documentation that is clear to an expert may be opaque to a beginner, and documentation written for beginners is often too verbose for experts.
Completeness: The documentation covers everything its audience needs to accomplish their goals. Missing information forces readers to find answers elsewhere (often inefficiently) or make incorrect assumptions.
These three parameters frequently trade off against one another. Maximizing accuracy and completeness can produce documentation that is so dense it fails on clarity. The right balance depends on the audience and the purpose.
Deprecating Documents
Documentation debt includes not just missing or inaccurate documentation but also stale documentation that describes a system that no longer exists. Stale documentation should be deprecated and eventually deleted, with the same discipline applied to dead code.
Deprecation process:
- Mark the document as deprecated (with a date and a pointer to the replacement if one exists)
- Leave it in place long enough for regular users to notice the deprecation notice
- Delete it once the deprecation period has passed
The failure mode to avoid: leaving stale documentation in place indefinitely because deleting it feels risky. Stale documentation that is never deleted becomes a minefield — readers cannot tell which documentation is current and which is obsolete.
When to Involve Technical Writers
Technical writers are skilled at structure, clarity, and audience-awareness. Engineers are the subject-matter experts. The best documentation results from collaboration between the two.
Involve technical writers when:
- Documentation will be read by a large external audience
- The team is producing tutorials or conceptual guides that require significant structure
- Existing documentation is structurally confusing and needs a rewrite
- The team does not have engineering time to invest in documentation quality
Do not depend on technical writers for:
- Inline code comments (engineers own these)
- Design documents (engineers write these before implementation)
- API reference documentation (generated from engineer-written doc comments)
The rule of thumb: technical writers polish and structure; engineers are the primary authors of technical content about the systems they build.
TL;DRs
- Documentation is like code: it needs ownership, review, and maintenance.
- Every engineer is responsible for the documentation of the systems they build.
- Documentation should be written for a specific audience — documentation written for everyone is useful to no one.
- There are several types of documentation: reference docs, design docs, tutorials, conceptual docs, and landing pages — each serves a different purpose and requires different writing approaches.
- Documentation quality is determined by accuracy, clarity, and completeness.
- Good documentation follows the reader’s mental journey: beginning (orient), middle (deliver), end (close the loop).
- Stale documentation should be deprecated and deleted rather than allowed to accumulate indefinitely.
- Technical writers are editors and structure specialists; engineers are the primary authors of technical documentation.
- The WHO WHAT WHEN WHERE WHY framework helps authors define what they are writing and for whom before they begin.
Key Takeaways
- Documentation is a first-class engineering artifact — it requires ownership, review, and maintenance on the same terms as code, and its absence creates a form of technical debt that compounds over time.
- “Documentation” is broader than formal reference material: it includes inline comments, design documents, tutorials, conceptual guides, READMEs, and landing pages — and the same quality standards apply to all of them.
- Engineers resist documentation because there is no immediate feedback loop: missing or wrong documentation fails silently, surfacing its absence only when someone needs it and cannot find it or is actively misled.
- Every documentation artifact should be written for a specific audience — beginners need tutorials and defined vocabulary; experts need accurate, lookup-oriented reference documentation; cross-functional audiences need structure that allows different readers to navigate to what they need.
- The WHO WHAT WHEN WHERE WHY framework helps authors clarify the purpose, scope, audience, and context of a document before writing — the inability to answer these questions is a signal that the documentation will fail its readers.
- Tutorials are the hardest documentation to maintain: they must work end-to-end in a real environment, and changes to any part of the stack can break them silently — they require the most active maintenance of any documentation type.
- Stale documentation is worse than no documentation: it creates false confidence, misleading readers who assume it is accurate. Deprecated documents should be deleted with the same discipline applied to dead code.
- Design documents serve three purposes: they force the author to think the problem through before coding; they allow peers to review the design before significant implementation is committed; and they create a permanent record of design intent.
- Documentation quality has three parameters — accuracy, clarity, and completeness — which frequently trade off against one another, with the right balance depending on audience and purpose.
- Technical writers are collaborators, not substitutes: they provide structure, clarity, and audience-awareness; engineers are the primary authors of technical content about the systems they build.
Related Resources
- ch09-code-review — Code review and documentation share the theme of making knowledge legible and creating a culture of shared ownership
- ch11-testing — Testing, like documentation, is a practice where investment compounds over time
- SAHT Chapter 1 — Architectural Decision Records as a specific, high-value documentation form for architectural decisions
- TSEP Chapter 4 — Technical leadership and the role of written artifacts in distributing organizational knowledge
Last Updated: 2026-06-02