docs-standards

name	docs-standards
description	Write clear, scannable project documentation
domain	documentation
confidence	high
source	template

Context

Documentation in this repository should be easy to scan, task-oriented, and accurate for the current codebase.

Patterns

Style

• Use sentence-case headings
• Prefer active voice and direct instructions
• Write for the reader as "you"
• Keep paragraphs short; use bullets and tables when they improve scanning
• Prefer plain language over slogans or hype

Structure

For feature or workflow docs, prefer:

1. Title
2. Short overview
3. Prerequisites or assumptions
4. Step-by-step instructions
5. Validation or expected outcome
6. Related references

Maintenance

• Update docs in the same change when behavior, commands, or file locations change
• Include real paths and commands from the repo
• Remove stale examples instead of letting them drift

Examples

✓ Good:

• "Run npm --prefix scripts run validate -- --input <path-to-json> to validate discovered links."
• "The catalog is published from docs/data/catalog.json."

✗ Poor:

• "Use the amazing workflow below"
• Long blocks of narrative where a short checklist would work better
• Examples that no longer match the repository layout

Anti-patterns

• Title case headings used inconsistently
• Passive voice when giving instructions
• Placeholder text left in committed docs
• Updating code without updating the related documentation