Chapter 10 Flashcards — Documentation
What is the broad definition of “documentation” in Chapter 10, and why does the broad definition matter?
?
Documentation includes any written artifact communicating information about code, systems, or processes: inline code comments, API reference docs, design documents, tutorials, conceptual guides, READMEs, and landing pages. The broad definition matters because engineers often treat inline comments as “not really documentation” and apply less rigor to them. The same quality standards — accuracy, clarity, audience-awareness — apply to all written artifacts regardless of form.
What is documentation debt, and how does it differ from ordinary technical debt?
?
Documentation debt is the accumulated backlog of missing, incorrect, or outdated documentation. Like technical debt, it compounds when not addressed — but documentation debt has a uniquely insidious failure mode: stale documentation is often worse than no documentation, because it creates false confidence. Readers who assume documentation is accurate and act on incorrect information may make worse decisions than readers who know no documentation exists.
Why do engineers resist writing documentation? Name at least four root causes.
?
- No immediate feedback loop — missing/wrong documentation fails silently; nothing breaks until someone needs it. 2. Seen as someone else’s job — engineers assume technical writers own documentation. 3. Documentation goes stale — investment seems wasted when systems change. 4. Feels unproductive — the value is invisible until someone benefits from it later. 5. Not knowing what to write — deep familiarity with a system creates blindness to what beginners need. The authors address all five: documentation ownership, audience-awareness, and treating docs like code solve most of them.
What does it mean for documentation to be “like code”?
?
Documentation, like code, requires: ownership (a designated owner who keeps it accurate as the system evolves), review (examining documentation before it is published to catch inaccuracies and audience mismatches), and maintenance (updating documentation as the system changes, treating updates as part of “done”). The same lifecycle applies: create with review, assign an owner, maintain as the system evolves, deprecate and delete when no longer relevant.
Why is a non-expert reviewer often the most valuable reviewer for documentation?
?
Documentation is written for readers who don’t already know the system. A non-expert reviewer experiences the documentation as its actual audience would — encountering the same gaps, undefined terms, and unclear explanations. If a non-expert reviewer cannot understand a document, neither can the beginner or newcomer the document is meant to serve. Subject-matter experts reviewing documentation often fill in gaps unconsciously, missing the places where a reader would get lost.
What are the three primary audience types for documentation, and what does each type need?
?
Beginners: encountering the system for the first time; need vocabulary defined, working examples they can run without modification, step-by-step task guidance, and “why” alongside “what.” Experts: already understand the system; need accurate, complete, lookup-oriented reference material organized for quick navigation rather than linear reading. Cross-functional audiences: readers from multiple domains (engineers, PMs, partners); need defined terms, minimal deep-technical detail, and clear structure for navigation.
What are the five documentation types covered in Chapter 10?
?
- Reference documentation — exhaustive description of APIs, functions, parameters, and return values; generated from doc comments; lookup-oriented for experts. 2. Design documents — pre-implementation design artifacts describing the problem, alternatives, and chosen approach. 3. Tutorials — step-by-step task guidance from start to working result for beginners. 4. Conceptual documentation — explains how a system works and why, providing the mental model readers need. 5. Landing pages — navigation documents that orient readers and direct them to the right resource.
What is the defining characteristic of a good tutorial?
?
A reader who follows the tutorial should end up with a working result. Good tutorials start from a known, reproducible state; include every step without assuming environment configuration; provide commands that can be copy-pasted and run; verify success at each step; and point to next steps. The failure mode: steps that skip setup, contain untested commands, or assume configuration the reader doesn’t have — breaking silently when the environment differs.
Why are tutorials the hardest documentation type to maintain?
?
Tutorials must work end-to-end in a real environment, and any change to any part of the stack can break them silently. A tutorial might describe a command whose flags changed, a UI whose layout changed, or a prerequisite whose installation instructions changed — and none of these breaks produce an error in the documentation itself. Tutorials require active, regular validation to remain useful, unlike reference docs (where inaccuracies are more localized).
What are the three purposes of a design document?
?
- Forces the author to think the problem through before writing code — the act of writing the design surfaces gaps and inconsistencies in the thinking. 2. Allows peers to review the design before significant implementation work is committed — changing a design document is much cheaper than refactoring implemented code. 3. Creates a permanent record of design intent — future engineers can consult the design document to understand why the system is structured as it is, rather than reverse-engineering intent from the code.
What is conceptual documentation and what problem does it solve?
?
Conceptual documentation explains how a system works and why it is designed as it is, without guiding the reader to accomplish a specific task. It answers “what is this and how does it work?” rather than “how do I do X?” It solves the problem of readers who must understand the whole before they can effectively work on the parts — providing the mental model needed to use reference documentation effectively and understand non-obvious design decisions.
What is the purpose of a landing page, and what is the failure mode of a poor one?
?
A landing page is a navigation document: it orients the reader within a documentation space and directs them to the right resource. It explains what the documentation space covers, lists main resources with brief descriptions, and is organized to match how readers navigate. The failure mode of a poor landing page: new users cannot find the right documentation and spend time on a scavenger hunt — or, worse, read the wrong documentation because the landing page didn’t make the distinctions clear.
What is the WHO WHAT WHEN WHERE WHY framework in documentation?
?
A five-question framework for clarifying the purpose and scope of any documentation artifact: WHO is this for (audience, background, expertise)? WHAT does it cover (scope)? WHEN should a reader consult it (stage of their work)? WHERE does it live (how do readers find it)? WHY does it exist (what problem does it solve)? Authors who cannot answer these questions clearly are likely to write documentation that fails its intended readers. The framework also evaluates existing documentation.
What is the beginning/middle/end structure for documentation?
?
Beginning: Orient the reader — who is this for, what will they learn, what should they know first? Tells the reader immediately whether this document is for them. Middle: Deliver what was promised — use clear headings, working examples, and progressive disclosure (most common case first, complexity added gradually). End: Close the loop — summarize what was covered, point to next steps and related resources. This structure mirrors the reader’s mental journey rather than the system’s internal structure.
What are the three parameters of documentation quality, and how do they trade off?
?
Accuracy: the documentation correctly describes the system — inaccurate documentation is worse than none. Clarity: the documentation can be understood by its intended audience without significant effort — depends entirely on audience knowledge. Completeness: the documentation covers everything the audience needs. They trade off: maximizing accuracy and completeness produces documentation so dense it fails on clarity. The right balance depends on audience and purpose; expert reference docs optimize for accuracy and completeness; beginner tutorials optimize for clarity.
Why is accuracy the most critical parameter of the three, especially for reference documentation?
?
Because inaccurate reference documentation is actively harmful — a reader who consults it and acts on incorrect information about an API’s behavior, parameters, or return values may introduce bugs, security vulnerabilities, or data corruption. Missing information (a completeness gap) is typically discovered quickly; wrong information (an accuracy gap) may be acted upon without question. Reference documentation is the canonical source of truth; inaccuracy in that source corrupts downstream decisions.
How should stale documentation be handled, and what is the failure mode of the alternative?
?
Stale documentation should be deprecated (marked with a date and pointer to the replacement), left in place during a transition period, then deleted. The failure mode of leaving stale documentation in place indefinitely: readers cannot distinguish current from obsolete documentation, creating a minefield where following any document risks acting on outdated information. Stale documentation should be treated like dead code: delete it with the same discipline rather than letting it accumulate.
What is the correct division of responsibility between engineers and technical writers?
?
Engineers are the primary authors of technical content about the systems they build: inline comments, design documents, API reference documentation generated from doc comments. Technical writers provide structure, clarity, and audience-awareness — they polish and edit; they write tutorials and conceptual guides in collaboration with engineers; they rewrite documentation that is structurally confusing. Engineers own the technical accuracy; technical writers own the communication quality. Neither substitutes for the other.
Why should every public API be documented, according to Chapter 10?
?
Because the alternative forces every caller to read the implementation to understand how to use the function — an exponential cost as the number of callers grows. Public APIs are the interfaces through which other engineers interact with a system; undocumented interfaces require each new user to reverse-engineer intent, accumulate incorrect mental models, or ask the author directly. Documentation of public APIs is not optional at Google; it is part of the definition of a releasable API.
What makes documentation for experts different from documentation for beginners?
?
Expert documentation assumes vocabulary and system familiarity — it can use system-specific terms without definition, skip motivating explanations, and prioritize completeness and accuracy over exposition. It is organized for lookup rather than linear reading — experts navigate to what they need rather than reading front to back. Beginner documentation must define terms, explain the “why,” provide working examples, and guide the reader step by step. Writing documentation for both audiences simultaneously typically fails both.
What is the relationship between documentation ownership and documentation accuracy over time?
?
Documentation without an owner drifts toward inaccuracy as the system evolves. Changes to the system are not reflected in documentation if no one is responsible for keeping them in sync. Documentation ownership — co-locating doc ownership with code ownership so the team that changes the system also updates its documentation — is the structural solution to documentation decay. Making documentation updates part of the “definition of done” for any change to documented behavior is the process-level enforcement.
What is the key principle behind the “documentation as code” metaphor?
?
That the practices that keep code healthy over time — ownership, review, maintenance, refactoring, and deletion of dead artifacts — also keep documentation healthy. Just as code without an owner accumulates technical debt and is eventually abandoned, documentation without an owner accumulates inaccuracies and is eventually ignored. Applying software engineering discipline to documentation (ownership, review gates, deprecation processes) addresses the root causes of documentation failure systematically rather than hoping engineers will maintain it voluntarily.
What role does audience-awareness play in determining documentation structure?
?
Audience determines everything: vocabulary (what terms to define vs. assume), structure (linear narrative vs. lookup-oriented), depth (step-by-step explanation vs. complete-but-dense reference), and scope (task-oriented tutorial vs. comprehensive conceptual overview). Documentation written without a defined audience is typically too advanced for beginners and too basic for experts, satisfying neither. The WHO question in the WHO WHAT WHEN WHERE WHY framework is the first question because its answer shapes all subsequent decisions.
Total Cards: 23
Review Time: ~18 minutes
Priority: HIGH
Last Updated: 2026-06-02