documentation-standardslisted

## Purpose Give any doc you write or edit a consistent shape so readers (and agents) can scan it, trust it, and find what they need without re-deriving your conventions each time. Use this whenever you're writing a README section, a docs/ page, an agent-facing instruction file (AGENTS.md/CLAUDE.md-style), or reviewing someone else's doc for structural issues. ## When to use it - Writing a new doc section or page from scratch. - Reviewing an existing doc for structure, not just factual accuracy (pair with the drift-check skill for accuracy). - Deciding whether new content belongs in an existing doc or needs its own page. ## Conventions ### Structure - Lead with what the thing is and why it exists before diving into how to use it. A reader deciding whether to keep reading needs that in the first sentence or two. - Use headings that describe content, not narrate process ("Configuration" not "How We Set This Up"). Keep heading depth shallow — two or three levels is almost always enough. - Put the most commonly needed information first (quickstart, common commands) and push edge cases, advanced options, and rationale further down or into a linked doc. ### Examples - Every non-trivial command or API shown should be a working, copy-pasteable example, not pseudocode. If you can't verify it runs, say so explicitly rather than presenting it as tested. - Show the expected output or result when it's not obvious, especially for CLI commands and API calls — readers verify they did it