docs

Docs

Reader and purpose

• Identify the reader’s goal and existing knowledge. Write to fill the gap between them.
• Choose content and structure for the reader’s purpose: learning, doing, looking up facts, or understanding why.
• Keep each page focused on its purpose; link to material serving other needs.
• Include details that enable progress, prevent likely misunderstandings, or explain meaningful constraints.
• Describe behavior and contracts without requiring readers to inspect source code. Include internals only when the reader needs them.

Structure

• Lead with what the reader came for.
• Put prerequisites and conditions before the actions they affect.
• Keep the main path easy to follow. Place optional detail and alternate paths where readers need them.
• Use descriptive headings and a logical heading hierarchy. Add sections only when their content earns a place.
• Keep each paragraph focused on one idea. Use numbered lists for sequences, bullets for related items, and tables for comparisons.
• Keep each fact in one authoritative place; link when readers need further detail.

Language

• Use plain, concrete words and direct sentences.
• Use the same term for the same concept, matching the product’s names. Explain unfamiliar terms when needed.
• Make clear who acts, what changes, and under which conditions.
• Remove filler, promotional language, decorative phrasing, and repetition.
• Remove restatements of code or examples that add no explanation, orientation, or useful confirmation for the intended reader.
• Use examples to resolve uncertainty. Keep them focused and complete enough for their intended use.

Accuracy and context

• Verify claims and examples against relevant sources. Do not invent missing facts.
• Check procedures from the reader’s stated starting point. Verify that the steps produce the promised outcome.
• Make the document understandable without the chat. Exclude conversation references, drafting commentary, and assignment history.
• Describe current behavior. Include historical decisions only when they explain something the reader still needs to understand.

Final pass

• For each passage, ask: “What does this help the intended reader do or understand?” Remove anything without a useful answer.
• Check that readers can find what they need without searching through unrelated detail.
• Minimize the reader’s effort, including the effort caused by missing context or omitted steps.