Docs Writing Standard

February 5, 2026 ยท View on GitHub

Purpose

Define consistent structure, markdown style, and explanation patterns for project docs.

Core Principles

  • Lead with user outcome, then steps, then edge cases.
  • One page should have one clear intent.
  • Prefer short concrete statements over broad prose.
  • Use stable terms (AndroidMenu, Build Variants, run.config_path) consistently.

Page Type Templates

Start Pages

Use sections in this order:

  1. Purpose
  2. Prerequisites
  3. Setup or Steps
  4. Validate (how to confirm success)
  5. Next steps

Guides

Use sections in this order:

  1. Purpose
  2. Default behavior or Mental model
  3. Controls or Entry points
  4. Recommended flow
  5. Related docs

Reference Pages

Use sections in this order:

  1. Scope
  2. Definitions/Tables
  3. Examples
  4. Related docs

Troubleshooting Pages

Use sections in this order:

  1. How to use this page
  2. Baseline checks
  3. Symptom blocks (Quick checks, Fix)
  4. Related docs

Markdown Conventions

  • Keep headings concise and in Title Case.
  • Use numbered lists (1. style) for procedures.
  • Use tables for command/keymap/item inventories.
  • Wrap commands, paths, options, and key names in backticks.
  • Prefer fenced code blocks with language identifiers.
  • End pages with a Related Docs section.

Explanation Pattern

Use this order for each important concept:

  1. What it is
  2. Why it matters
  3. How to use it
  4. How to validate it
  5. Where to go next
  • Keep canonical pages in the new docs structure.
  • Keep legacy path pages as redirects while external links still depend on them.
  • Update docs/README.md whenever docs paths or ownership change.