documentation-standards

name

documentation-standards

description

Standards and patterns for creating, reviewing, and improving technical documentation — covering markdown formatting, heading hierarchy, code blocks, links, writing style, accessibility, and language-native doc toolchains (rustdoc, godoc, Sphinx, TypeDoc, Javadoc, DocC, ExDoc). Use this skill whenever the user wants to review documentation quality, audit markdown formatting, fix document structure, improve technical writing, check doc comment coverage, enforce doc standards, write better docs, or asks about documentation best practices. Also triggers for language-specific doc toolchain questions (rustdoc, godoc, pydoc, JSDoc/TSDoc, Javadoc/KDoc, DocC, ExDoc) and site generator integration (MkDocs, Sphinx, Docusaurus, Astro Starlight). If the user mentions "docs", "documentation", "README", "writing style", "doc comments", "markdown", or "technical writing" in a quality or standards context, this skill likely applies.

Documentation Standards

Standards and patterns for creating, reviewing, and improving technical documentation. Good documentation reduces support burden, accelerates onboarding, and builds user trust — these standards exist to make that happen consistently.

Core Quality Principles

Documentation fails readers in predictable ways: unclear language forces re-reading, missing context creates dead ends, stale examples break trust, and inconsistent terminology confuses. These four principles address the root causes.

Clarity

• Write for the reader's level of expertise
• Define technical terms on first use
• Use active voice and direct language — "Configure the server" not "The server should be configured"
• Avoid jargon unless the audience expects it

Completeness

• Cover all essential topics for the document's purpose
• Include prerequisites and requirements upfront
• Provide working examples for technical concepts
• Document edge cases, limitations, and known issues

Accuracy

• Verify all technical details against current implementation
• Test code examples before including them — broken examples erode trust faster than missing docs
• Update documentation when code changes
• Remove or clearly mark deprecated content

Consistency

• Follow established style guides (project or industry standard)
• Use consistent terminology throughout — same concept, same name everywhere
• Maintain uniform formatting and structure
• Apply consistent code example styles

Document Structure

Standard Sections

README files:

1. Title and brief description
2. Features/highlights
3. Installation/setup
4. Quick start/usage
5. Configuration options
6. API reference (or link)
7. Contributing guidelines
8. License

Technical guides:

1. Overview/introduction
2. Prerequisites
3. Step-by-step instructions
4. Examples
5. Troubleshooting
6. Related resources

API documentation:

1. Endpoint/function description
2. Parameters (required/optional)
3. Request/response formats
4. Code examples
5. Error responses
6. Rate limits/constraints

Heading Hierarchy

Headings serve as both navigation and outline — screen readers, search engines, and table-of-contents generators all depend on correct hierarchy.

• H1: Document title (one per document)
• H2: Major sections
• H3: Subsections
• H4: Minor subsections (use sparingly)
• Avoid H5/H6 — if you need them, the document likely needs restructuring into separate pages

Markdown Best Practices

Code Blocks

Always specify language for syntax highlighting:

```python
def example():
    return "highlighted"
```

Use inline code for:

• File names: config.yaml
• Commands: npm install
• Variable names: user_id
• Short code references: return True

Links

Internal links:

• Use relative paths: [Setup](./setup.md)
• Verify links exist and are accurate
• Use descriptive link text (not "click here")

External links:

• Include for authoritative sources
• Consider link rot (prefer stable URLs)
• Add context for why the link is relevant

Lists

Ordered lists for sequential steps:

1. First do this
2. Then do this
3. Finally do this

Unordered lists for non-sequential items:

• Feature A
• Feature B
• Feature C

Tables

Use tables for structured data comparison:

Feature	Free	Pro
Users	5	100
Storage	1GB	50GB

Avoid tables for simple lists or prose content.

Admonitions

Use consistent patterns for callouts:

> **Note:** Additional information

> **Warning:** Important caution

> **Tip:** Helpful suggestion

Review Checklist

When reviewing documentation, evaluate:

Content Quality

• Purpose is clear from introduction
• All claims are accurate and verifiable
• Examples are complete and working
• Prerequisites are documented
• Edge cases are addressed

Structure

• Logical flow from introduction to details
• Appropriate heading hierarchy
• Related content is grouped together
• Navigation is intuitive

Formatting

• Code blocks have language specified
• Links are valid and descriptive
• Lists are used appropriately
• Tables are well-formatted
• Consistent style throughout

Accessibility

• Images have alt text
• Color is not sole indicator
• Content works without images
• Headings describe content

Common Issues

Outdated Content

• Signs: Version numbers don't match, deprecated APIs referenced, screenshots show old UI
• Fix: Update or remove outdated sections, add "last updated" dates

Missing Context

• Signs: Assumes knowledge not provided, jumps into details, missing prerequisites
• Fix: Add introduction, document assumptions, link to prerequisites

Inconsistent Terminology

• Signs: Same concept called different names, abbreviations undefined
• Fix: Create glossary, standardize terms, define on first use

Broken Examples

• Signs: Code doesn't compile, commands fail, outputs don't match
• Fix: Test all examples, update for current versions, add expected outputs

Poor Organization

• Signs: Related content scattered, unclear navigation, buried important info
• Fix: Restructure by topic, add table of contents, move critical info up

Writing Style

Effective technical writing is invisible — readers absorb the information without noticing the prose. These patterns make that happen.

Voice and Tone

• Use active voice: "Configure the server" not "The server should be configured"
• Be direct: "Run the command" not "You might want to run the command"
• Stay objective: Focus on facts and procedures
• Use imperative form for instructions: "Install the package" not "You should install the package"

Technical Accuracy

• Verify all technical claims against current implementation
• Include version numbers where relevant — readers need to know if docs match their setup
• Test commands and code before documenting
• Reference authoritative sources

Audience Awareness

• Define the target audience clearly — who is this document for?
• Adjust complexity to match audience expertise
• Provide links for background knowledge rather than inline explanations
• Don't over-explain basics to experts — it signals the docs aren't for them

Language Doc Toolchains

Language-native documentation toolchains (rustdoc, godoc, Sphinx, TypeDoc, Javadoc/Dokka, DocC, DocFX, ExDoc) generate API reference from source code comments. When a project uses one, in-source doc comments are the authoritative API documentation — not separate markdown files.

General principles:

1. Source comments are the API reference — not separate markdown files
2. Doc toolchain build must pass clean without warnings or errors
3. All public API must be documented — missing doc comments are a review finding
4. Examples should be testable (doctests, example functions)
5. Pick one doc comment style per project and enforce it

For per-language conventions, build commands, review criteria, and configuration examples, see references/language-toolchains.md.

Integration with Site Generators

When a project uses a documentation site generator, follow its conventions:

Generator	Key Files	Notes
MkDocs	mkdocs.yml	Admonition syntax, search/versioning plugins
Sphinx	conf.py	reStructuredText, autodoc integration
Docusaurus	docusaurus.config.js	MDX support, sidebar config, versioning
Astro Starlight	astro.config.mjs	Content collections in src/content/docs/, i18n, component islands

Additional Resources

Reference Files

For detailed guidance, consult:

• references/style-guide.md - Comprehensive writing style rules
• references/review-criteria.md - Detailed review criteria and scoring
• references/language-toolchains.md - Per-language doc toolchain conventions (Rust, Go, Python, TypeScript, Java/Kotlin, Swift, C#, Elixir)

Example Files

Working examples in examples/:

• good-readme.md - Well-structured README template
• api-doc-template.md - API documentation template