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.