Write good documentation
Write for a specific human who needs to understand something, decide something, or complete a task. Produce the shortest document that lets that reader succeed without losing facts, caveats, safety information, or necessary context.
This skill governs documentation prose and structure. It is not a source of product facts. Derive facts from the user's material and authoritative project sources.
Priorities
Resolve tradeoffs in this order:
- Technical truth and safety. Do not invent, weaken, or silently change facts, requirements, uncertainty, warnings, code, commands, identifiers, or interface labels.
- The reader's outcome. Include what the intended reader needs to act or understand. Exclude material that serves only the author, implementation history, or an appearance of completeness.
- Findability and sequence. Make the answer easy to locate, scan, and follow from a search result or direct link.
- Clarity and concision. Prefer direct, literal, natural language. Remove avoidable friction and repetition.
- Consistency and mechanics. Follow the user's requirements and the project's established style before this skill's defaults.
Do not sacrifice a higher priority to satisfy a lower one.
Before writing
Use the available context before asking the user for information.
- Read the request and any supplied source material.
- When working in a repository, inspect the relevant existing docs, templates, code, tests, configuration, issues, and pull requests. Use the smallest evidence set that establishes the facts and local conventions.
- Identify:
- the intended reader;
- what the reader must understand, decide, or accomplish;
- what the reader can already be expected to know;
- the document's primary job;
- the requested scope, format, length, dialect, and tone.
- Record exact material that must not drift: product and feature names, UI labels, API names, identifiers, commands, code, paths, filenames, links, values, dates, limits, warnings, and contractual wording.
- Separate established facts from inferences, proposals, and unknowns. Verify consequential claims. When evidence is unavailable, preserve the uncertainty or use an explicit placeholder instead of guessing.
Infer reasonable defaults from the project and request. Ask a question only when an unresolved ambiguity would materially change the document and cannot be resolved from available sources.
Choose one primary job
A document becomes muddy when it tries to teach, direct, explain, and catalog everything at once. Choose the reader's main need:
| Reader need |
Primary document job |
| Learn by doing in a controlled path |
Tutorial |
| Complete a real task |
How-to guide |
| Look up exact facts |
Reference |
| Understand why or how something works |
Explanation or concept guide |
| Evaluate or record a technical choice |
Design document, RFC, or ADR |
| Diagnose, recover, or operate a system |
Troubleshooting guide or runbook |
| Start using a project or team system |
README or onboarding guide |
| Move between versions or behavior |
Migration guide or release note |
A page can contain supporting material, but one job must control its structure. Link to a different document rather than burying a second document inside the first.
Read Document shapes before creating or substantially restructuring a full document.
Workflow
1. Build a truth set
Collect only the facts needed for the requested scope. Note prerequisites, permissions, constraints, failure modes, compatibility, side effects, and unresolved questions. Treat implementation details as evidence, not automatically as reader-facing content.
For code, commands, APIs, UI, architecture, or operational material, read Technical fidelity.
2. Plan the reader's path
Write a one-sentence private statement of the document's job:
After reading this, [reader] can [outcome] under [conditions].
Use it to decide what belongs. Order information by the reader's workflow or reasoning, not by the order in which the author discovered it or the product is implemented.
Usually:
- Lead with the outcome, decision, or essential context.
- State prerequisites and governing conditions before dependent material.
- Present the recommended path before alternatives.
- Put warnings immediately before the risky action.
- Give verification, rollback, or next steps where the reader needs them.
3. Draft the minimum complete version
Write the smallest version that is accurate and usable.
- Address the reader as you in task-oriented content. Use imperatives for steps.
- Use active voice and name the actor when responsibility matters.
- Put conditions before the instruction or result they govern.
- Use one term for one concept. Do not rotate synonyms for variety.
- Define unfamiliar terms at the first useful mention.
- Prefer a clear default over an undifferentiated menu of options.
- Use examples only when they remove a real ambiguity or make an abstraction concrete.
- Make every heading, list, table, note, and code block earn its place.
For dense, awkward, inflated, or AI-sounding prose, read Clear prose.
4. Compress without damaging meaning
Run a deletion pass after the content is correct.
Remove:
- pre-announcements such as “This document explains”;
- generic background that does not change a decision or action;
- repeated claims, conclusions, and transitions;
- sections added only because a template commonly contains them;
- headings that contain one short paragraph and add no navigation value;
- bullets that would read better as one or two sentences;
- obvious descriptions of code or UI that the reader can already see;
- adjectives and adverbs that do not add testable meaning;
- meta-commentary about the writing, research, or answer.
Do not remove prerequisites, distinctions, warnings, exceptions, rationale for a consequential decision, or repetition required for safe standalone use.
5. Validate as a first-time reader
Read Final review before finalizing a substantial draft, rewrite, or formal documentation review. Fix the document, then review it again.
Load references only when needed
Progressive disclosure matters. Do not load every reference for every task.
| Situation |
Read |
| Creating or reshaping a README, tutorial, how-to, reference page, concept guide, design doc, ADR, runbook, onboarding guide, migration guide, or release note |
Document shapes |
| Rewriting for clarity, shortening prose, removing repetition, fixing tone, or avoiding common agent-writing patterns |
Clear prose |
| Writing numbered steps, tutorials, operational procedures, troubleshooting, incident response, or destructive actions |
Procedures and troubleshooting |
| Documenting code, commands, output, APIs, UI, architecture, configuration, examples, or exact technical literals |
Technical fidelity |
| Deciding headings, paragraphs, lists, tables, links, notices, images, Markdown, HTML, accessibility, localization, or inclusive wording |
Structure and accessibility |
| Resolving spelling, capitalization, punctuation, numbers, dates, units, modality, or recurring word-choice questions |
Style reference |
| A concrete before-and-after pattern would help |
Examples |
| A condensed rule is insufficient or likely to have changed |
Official source map |
| Finalizing a substantial document or formal audit |
Final review |
Do not open Style reference merely because the task contains prose. It is an edge-case and copyediting reference, not the writing workflow.
Common agent failures
Actively prevent these patterns:
- Generic openings: “In today's fast-paced world,” “This comprehensive guide,” or a paragraph that repeats the title.
- Documentation-shaped padding: an unnecessary overview, benefits section, key takeaways, best practices list, FAQ, and conclusion added to make a short topic look complete.
- Architecture dumps: describing modules in implementation order when the reader needs a task or decision path.
- Bullet soup: converting every thought into a list, including items that are not parallel or easier to scan.
- Heading inflation: many tiny sections, repeated section names, or headings that do not help retrieval.
- Synthetic certainty: filling evidence gaps with plausible defaults, behavior, limits, reasons, or future plans.
- Style overreach: changing code, commands, identifiers, UI labels, established terminology, dialect, or unrelated formatting while “cleaning up” prose.
- Option dumping: listing every possible approach without choosing or explaining a default.
- Repeated conclusions: restating the same point in the opening, body, summary, and closing.
- Marketing language: “seamless,” “robust,” “powerful,” “revolutionary,” “best-in-class,” or unsupported claims about ease, speed, security, or reliability.
- Reader blame: “obviously,” “simply,” “just,” “easy,” or instructions that assume failure is the reader's fault.
- Visual-only directions: “click the button on the right,” “see above,” or relying on color, position, punctuation, or an image to carry essential meaning.
Editing existing documentation
Match the requested scope.
- For a local edit, make a local edit. Do not restyle the whole file.
- Preserve supported facts, qualifications, warnings, anchors, links, terminology, and document history.
- Preserve exact literals unless the user asked to correct them and an authoritative source supports the correction.
- Match a coherent existing dialect, tone, heading system, and markup convention.
- Restructure only when requested or when the current structure materially blocks the reader's goal.
- Do not “improve” an historical ADR or release note by rewriting its decision in light of later events. Add a superseding record when appropriate.
- Do not remove intentional repetition from standalone procedures, warnings, generated reference sections, or content commonly entered from search.
Review behavior
Follow the user's requested review format. Otherwise:
- When asked to edit, return the improved text or patch rather than an essay about style.
- When asked to review, report only material issues. For each issue, give the location, reader impact, and a concrete revision.
- Distinguish factual or usability problems from optional style preferences.
- Rank accuracy, safety, task completion, ambiguity, accessibility, and maintenance cost above cosmetic consistency.
- Do not cite this skill or mention that prose was “Google style” inside the document unless the user asks for that context.
Default language choices
When the project does not establish a different convention:
- use American English;
- use sentence case for titles and headings;
- use a conversational, direct, respectful tone;
- use the serial comma;
- use must for requirements, can for capability or optional action, and might for possibility;
- avoid ambiguous should when a requirement, recommendation, expected state, or possibility can be stated precisely;
- use exact dates, versions, and lifecycle states instead of current, new, latest, or soon;
- use descriptive link text;
- put code-related literals in
code font and exact UI labels in bold.
1---
2name: write-good-docs
3description: Use this skill when the requested output will be human-facing documentation, or when existing documentation must be written, rewritten, shortened, reorganized, or reviewed. Trigger for READMEs, guides, tutorials, how-tos, reference docs, API or CLI docs, runbooks, troubleshooting, onboarding, architecture or design docs, RFCs or ADRs, migration guides, release notes, and docstrings or comments; also trigger on vague requests such as "document this," "write the docs," "clean up this README," or "make this guide clearer." Do not trigger for ad hoc explanations, marketing copy, email, chat, social posts, fiction, or code-only work unless documentation is a material deliverable.
4license: CC-BY-4.0; see ATTRIBUTION.md
5metadata:
6 version: "2.0.0"
7 source: https://skillmd.com/skills/tristanmanchester/write-good-docs
8 upstream: "Google developer documentation style guide"
9 research-date: "2026-08-18"
10---
11
12# Write good documentation
13
14Write for a specific human who needs to understand something, decide something, or complete a task. Produce the shortest document that lets that reader succeed without losing facts, caveats, safety information, or necessary context.
15
16This skill governs documentation prose and structure. It is not a source of product facts. Derive facts from the user's material and authoritative project sources.
17
18## Priorities
19
20Resolve tradeoffs in this order:
21
221. **Technical truth and safety.** Do not invent, weaken, or silently change facts, requirements, uncertainty, warnings, code, commands, identifiers, or interface labels.
232. **The reader's outcome.** Include what the intended reader needs to act or understand. Exclude material that serves only the author, implementation history, or an appearance of completeness.
243. **Findability and sequence.** Make the answer easy to locate, scan, and follow from a search result or direct link.
254. **Clarity and concision.** Prefer direct, literal, natural language. Remove avoidable friction and repetition.
265. **Consistency and mechanics.** Follow the user's requirements and the project's established style before this skill's defaults.
27
28Do not sacrifice a higher priority to satisfy a lower one.
29
30## Before writing
31
32Use the available context before asking the user for information.
33
341. Read the request and any supplied source material.
352. When working in a repository, inspect the relevant existing docs, templates, code, tests, configuration, issues, and pull requests. Use the smallest evidence set that establishes the facts and local conventions.
363. Identify:
37 - the intended reader;
38 - what the reader must understand, decide, or accomplish;
39 - what the reader can already be expected to know;
40 - the document's primary job;
41 - the requested scope, format, length, dialect, and tone.
424. Record exact material that must not drift: product and feature names, UI labels, API names, identifiers, commands, code, paths, filenames, links, values, dates, limits, warnings, and contractual wording.
435. Separate established facts from inferences, proposals, and unknowns. Verify consequential claims. When evidence is unavailable, preserve the uncertainty or use an explicit placeholder instead of guessing.
44
45Infer reasonable defaults from the project and request. Ask a question only when an unresolved ambiguity would materially change the document and cannot be resolved from available sources.
46
47## Choose one primary job
48
49A document becomes muddy when it tries to teach, direct, explain, and catalog everything at once. Choose the reader's main need:
50
51| Reader need | Primary document job |
52|---|---|
53| Learn by doing in a controlled path | Tutorial |
54| Complete a real task | How-to guide |
55| Look up exact facts | Reference |
56| Understand why or how something works | Explanation or concept guide |
57| Evaluate or record a technical choice | Design document, RFC, or ADR |
58| Diagnose, recover, or operate a system | Troubleshooting guide or runbook |
59| Start using a project or team system | README or onboarding guide |
60| Move between versions or behavior | Migration guide or release note |
61
62A page can contain supporting material, but one job must control its structure. Link to a different document rather than burying a second document inside the first.
63
64Read [Document shapes](references/document-shapes.md) before creating or substantially restructuring a full document.
65
66## Workflow
67
68### 1. Build a truth set
69
70Collect only the facts needed for the requested scope. Note prerequisites, permissions, constraints, failure modes, compatibility, side effects, and unresolved questions. Treat implementation details as evidence, not automatically as reader-facing content.
71
72For code, commands, APIs, UI, architecture, or operational material, read [Technical fidelity](references/technical-fidelity.md).
73
74### 2. Plan the reader's path
75
76Write a one-sentence private statement of the document's job:
77
78> After reading this, **[reader]** can **[outcome]** under **[conditions]**.
79
80Use it to decide what belongs. Order information by the reader's workflow or reasoning, not by the order in which the author discovered it or the product is implemented.
81
82Usually:
83
841. Lead with the outcome, decision, or essential context.
852. State prerequisites and governing conditions before dependent material.
863. Present the recommended path before alternatives.
874. Put warnings immediately before the risky action.
885. Give verification, rollback, or next steps where the reader needs them.
89
90### 3. Draft the minimum complete version
91
92Write the smallest version that is accurate and usable.
93
94- Address the reader as **you** in task-oriented content. Use imperatives for steps.
95- Use active voice and name the actor when responsibility matters.
96- Put conditions before the instruction or result they govern.
97- Use one term for one concept. Do not rotate synonyms for variety.
98- Define unfamiliar terms at the first useful mention.
99- Prefer a clear default over an undifferentiated menu of options.
100- Use examples only when they remove a real ambiguity or make an abstraction concrete.
101- Make every heading, list, table, note, and code block earn its place.
102
103For dense, awkward, inflated, or AI-sounding prose, read [Clear prose](references/clear-prose.md).
104
105### 4. Compress without damaging meaning
106
107Run a deletion pass after the content is correct.
108
109Remove:
110
111- pre-announcements such as “This document explains”;
112- generic background that does not change a decision or action;
113- repeated claims, conclusions, and transitions;
114- sections added only because a template commonly contains them;
115- headings that contain one short paragraph and add no navigation value;
116- bullets that would read better as one or two sentences;
117- obvious descriptions of code or UI that the reader can already see;
118- adjectives and adverbs that do not add testable meaning;
119- meta-commentary about the writing, research, or answer.
120
121Do not remove prerequisites, distinctions, warnings, exceptions, rationale for a consequential decision, or repetition required for safe standalone use.
122
123### 5. Validate as a first-time reader
124
125Read [Final review](references/final-review.md) before finalizing a substantial draft, rewrite, or formal documentation review. Fix the document, then review it again.
126
127## Load references only when needed
128
129Progressive disclosure matters. Do not load every reference for every task.
130
131| Situation | Read |
132|---|---|
133| Creating or reshaping a README, tutorial, how-to, reference page, concept guide, design doc, ADR, runbook, onboarding guide, migration guide, or release note | [Document shapes](references/document-shapes.md) |
134| Rewriting for clarity, shortening prose, removing repetition, fixing tone, or avoiding common agent-writing patterns | [Clear prose](references/clear-prose.md) |
135| Writing numbered steps, tutorials, operational procedures, troubleshooting, incident response, or destructive actions | [Procedures and troubleshooting](references/procedures-and-troubleshooting.md) |
136| Documenting code, commands, output, APIs, UI, architecture, configuration, examples, or exact technical literals | [Technical fidelity](references/technical-fidelity.md) |
137| Deciding headings, paragraphs, lists, tables, links, notices, images, Markdown, HTML, accessibility, localization, or inclusive wording | [Structure and accessibility](references/structure-and-accessibility.md) |
138| Resolving spelling, capitalization, punctuation, numbers, dates, units, modality, or recurring word-choice questions | [Style reference](references/style-reference.md) |
139| A concrete before-and-after pattern would help | [Examples](references/examples.md) |
140| A condensed rule is insufficient or likely to have changed | [Official source map](references/source-map.md) |
141| Finalizing a substantial document or formal audit | [Final review](references/final-review.md) |
142
143Do not open [Style reference](references/style-reference.md) merely because the task contains prose. It is an edge-case and copyediting reference, not the writing workflow.
144
145## Common agent failures
146
147Actively prevent these patterns:
148
149- **Generic openings:** “In today's fast-paced world,” “This comprehensive guide,” or a paragraph that repeats the title.
150- **Documentation-shaped padding:** an unnecessary overview, benefits section, key takeaways, best practices list, FAQ, and conclusion added to make a short topic look complete.
151- **Architecture dumps:** describing modules in implementation order when the reader needs a task or decision path.
152- **Bullet soup:** converting every thought into a list, including items that are not parallel or easier to scan.
153- **Heading inflation:** many tiny sections, repeated section names, or headings that do not help retrieval.
154- **Synthetic certainty:** filling evidence gaps with plausible defaults, behavior, limits, reasons, or future plans.
155- **Style overreach:** changing code, commands, identifiers, UI labels, established terminology, dialect, or unrelated formatting while “cleaning up” prose.
156- **Option dumping:** listing every possible approach without choosing or explaining a default.
157- **Repeated conclusions:** restating the same point in the opening, body, summary, and closing.
158- **Marketing language:** “seamless,” “robust,” “powerful,” “revolutionary,” “best-in-class,” or unsupported claims about ease, speed, security, or reliability.
159- **Reader blame:** “obviously,” “simply,” “just,” “easy,” or instructions that assume failure is the reader's fault.
160- **Visual-only directions:** “click the button on the right,” “see above,” or relying on color, position, punctuation, or an image to carry essential meaning.
161
162## Editing existing documentation
163
164Match the requested scope.
165
166- For a local edit, make a local edit. Do not restyle the whole file.
167- Preserve supported facts, qualifications, warnings, anchors, links, terminology, and document history.
168- Preserve exact literals unless the user asked to correct them and an authoritative source supports the correction.
169- Match a coherent existing dialect, tone, heading system, and markup convention.
170- Restructure only when requested or when the current structure materially blocks the reader's goal.
171- Do not “improve” an historical ADR or release note by rewriting its decision in light of later events. Add a superseding record when appropriate.
172- Do not remove intentional repetition from standalone procedures, warnings, generated reference sections, or content commonly entered from search.
173
174## Review behavior
175
176Follow the user's requested review format. Otherwise:
177
178- When asked to edit, return the improved text or patch rather than an essay about style.
179- When asked to review, report only material issues. For each issue, give the location, reader impact, and a concrete revision.
180- Distinguish factual or usability problems from optional style preferences.
181- Rank accuracy, safety, task completion, ambiguity, accessibility, and maintenance cost above cosmetic consistency.
182- Do not cite this skill or mention that prose was “Google style” inside the document unless the user asks for that context.
183
184## Default language choices
185
186When the project does not establish a different convention:
187
188- use American English;
189- use sentence case for titles and headings;
190- use a conversational, direct, respectful tone;
191- use the serial comma;
192- use **must** for requirements, **can** for capability or optional action, and **might** for possibility;
193- avoid ambiguous **should** when a requirement, recommendation, expected state, or possibility can be stated precisely;
194- use exact dates, versions, and lifecycle states instead of **current**, **new**, **latest**, or **soon**;
195- use descriptive link text;
196- put code-related literals in `code font` and exact UI labels in **bold**.