documentation-standards

Documentation Standards

Types of Documentation

• User-facing docs

  • Explain features, configuration, and usage.
  • Assume no access to source code.

• Internal docs

  • Capture system behavior, architecture, and decisions for developers.
  • Include rationale and trade-offs.

• Inline docs / comments

  • Explain non-obvious implementation details or constraints.

Style & Tone

• Clear, concise, and concrete.
• Prefer active voice and simple sentences.
• Avoid unexplained acronyms and internal-only jargon.

Structure Guidelines

Feature Docs

• Overview
• Use cases
• Configuration and defaults
• Examples
• Limitations and edge cases
• Troubleshooting

Architecture Docs

• High-level diagram (or description)
• Components and responsibilities
• Data flows and interactions
• Trade-offs and constraints
• Links to related RFCs or ADRs

Maintenance Rules

• Documentation must be updated as part of behavior changes.
• Prefer small, incremental doc updates rather than large rewrites.
• Link docs to relevant issues or tickets where useful.

Formatting

• Use Markdown (.md) for text docs.
• Use consistent heading levels and lists.
• Include code blocks with language tags.