documentation-standards

Documentation Standards

Mandatory documentation gates are owned by the documentation rule (${HANDBOOK_ROOT}/rules/810-documentation.mdc), and Markdown-specific gates are owned by the Markdown rule (${HANDBOOK_ROOT}/rules/800-markdown.mdc). This skill owns document design, generated PNG guidance, templates, and writing workflows. External documentation research and tool selection are owned by the utilities rule (${HANDBOOK_ROOT}/rules/120-utilities.mdc).

Core Principles

1. Audience-First: Write for your reader, not yourself
2. Keep Current: Outdated docs are worse than no docs
3. Show, Don't Just Tell: Use examples and diagrams
4. Consistent Format: Follow established patterns

Hard Requirements (Writing)

• No AI slop - remove filler, keep docs concrete and task-oriented
• No Unicode em dashes or en dashes - never author U+2014 or U+2013; use commas, colons, parentheses, semicolons, or ASCII hyphens instead
• Clickable navigation - if readers may want to open a repo file, directory, section, ADR, rule, skill, script, workflow, or config, make it a Markdown link. Use backticks only when the path is a literal value, not a navigation target.
• Official terminology - use each vendor's current official product and service names, capitalization, and branding. Verify uncertain names against current vendor documentation. For example, write Amazon VPC, not AWS VPC; write AWS Lambda, not Amazon Lambda. Do not apply one naming prefix mechanically across a provider's services.

Voice

Prefer neutral/imperative phrasing - avoid "you/your" in professional docs. Canonical guidance: rules/810-documentation.mdc.

Diataxis Quick Guide

Use one primary documentation mode per page:

• Tutorial - learning by doing
• How-to guide - task completion
• Reference - factual lookup
• Explanation - concepts and rationale

Canonical Diataxis guidance lives in rules/810-documentation.mdc. Keep this skill concise and link back to the rule instead of duplicating detailed standards.