Documentation Standards

Documentation Standards

Templates, workflows, and checklists for creating documentation following Diataxis principles.

When to Use This Skill

Use when:

• Creating any type of documentation
• Need template for specific doc type
• Want checklist to verify doc completeness
• documentation-writer agent needs HOW guidance

Diataxis Framework Quick Reference

Documentation Types Overview

Quick Decision Tree

What does the reader need?
├─ Learn something new → Tutorial
├─ Accomplish a specific task → How-to
├─ Look up information → Reference
└─ Understand why/context → Explanation

Type Summaries and Checklists

Type 1: README (Root Project)

Diataxis: How-to (goal: get project running)

Required Sections:

1. Title + One-liner
2. Quick Start (fastest path to working)
3. Installation (step-by-step)
4. Usage (basic examples)
5. License

Checklist:

• Can someone get running in <5 minutes?
• Prerequisites clearly stated (checklist format)?
• Installation steps verified to work?
• Basic usage example included?

Guidelines: references/readme-guidelines.md Template: examples/readme-root-template.md

Quick Start Guide

Diataxis: How-to (goal: get running FAST)

When to Create: If README Quick Start section > 10 lines

Required Sections:

1. Time estimate upfront (with emoji title)
2. Prerequisites (checklist format with - [ ])
3. Steps with time per section and expected output
4. Verification that it works
5. Troubleshooting (top 2-3 issues)
6. "Need Help?" section with resources

Checklist:

• Time-boxed (stated upfront)?
• Every command copy-paste ready?
• Expected output shown for each step?
• Ends with verifiable working state?
• "Need Help?" section instead of "Next Steps"?

Guidelines: references/quickstart-guidelines.md Template: examples/quickstart-template.md

CONTRIBUTING.md

Diataxis: How-to (goal: enable contributions)

Required Sections:

1. How to Contribute (overview)
2. Reporting Bugs
3. Development Setup (with time estimate)
4. Pull Request Process
5. Code of Conduct (or link)

Checklist:

• Welcoming tone?
• Setup instructions tested?
• PR process clear?
• Response timeline mentioned?

Guidelines: references/contributing-guidelines.md Template: examples/contributing-template.md

Type 2: README (Module/Library)

Diataxis: Reference + How-to hybrid

Required Sections:

1. Purpose - What problem does this module solve?
2. API - Functions/classes exported
3. Usage Examples - Common use cases
4. Dependencies - What this module depends on

Checklist:

• Purpose clearly stated?
• All exports documented?
• Examples for main use cases?

Guidelines: references/readme-guidelines.md Template: examples/readme-module-template.md

Type 3: API Documentation

Diataxis: Reference (exhaustive, accurate)

Required Sections:

1. Endpoint - Method + Path
2. Authentication - Requirements
3. Request - Headers, params, body
4. Response - Success + all error cases
5. Examples - curl/code

Checklist:

• All parameters documented with types?
• All response codes covered?
• Request/response examples provided?
• Authentication requirements stated?

Guidelines: references/api-docs-guidelines.md Template: examples/api-docs-template.md

Type 4: Tutorial

Diataxis: Tutorial (learning-oriented)

Core Principles:

• Hand-holding: Every step explicit
• Confidence building: Small wins frequently
• Beginner-friendly: Assume nothing

Required Sections:

1. What you'll learn - Clear outcomes
2. Time estimate - Total and per section
3. Prerequisites - Checklist format
4. Steps - Numbered, explicit with checkpoints
5. Verification - How to know it worked
6. Troubleshooting - Common issues
7. Need Help? - Resources and next steps

Checklist:

• Can a complete beginner follow?
• Each step has verification?
• No assumed knowledge?
• Time estimates included?

Guidelines: references/tutorial-guidelines.md Template: examples/tutorial-template.md

Type 5: How-to Guide

Diataxis: How-to (goal-oriented)

Core Principles:

• Goal-focused: Solve specific problem
• Assumes knowledge: Reader knows basics
• Concise: Minimum steps to goal

Required Sections:

1. Goal - What reader will accomplish
2. Prerequisites - Required knowledge/setup
3. Steps - Direct path to goal
4. Troubleshooting - Common issues

Checklist:

• Goal clearly stated?
• Steps minimal but complete?
• No unnecessary explanation?

Guidelines: references/howto-guidelines.md Template: examples/howto-template.md

Type 6: Reference Documentation

Diataxis: Reference (information-oriented)

Core Principles:

• Exhaustive: All options documented
• Accurate: 100% correct, verified against code
• Consistent: Same format throughout

Required Sections:

1. Overview - What this covers
2. Index/TOC - Navigation
3. Entries - Consistent format per item
4. Cross-references - Links to related

Checklist:

• Every option/parameter documented?
• Format consistent throughout?
• Verified against actual code?
• Types/defaults specified?

Guidelines: references/reference-guidelines.md Template: examples/reference-docs-template.md

Type 7: Explanation / ADR

Diataxis: Explanation (understanding-oriented)

Core Principles:

• WHY-focused: Context and reasoning
• Long half-life: Stays relevant over time
• Contextual: Background and history

Required Sections (ADR Format):

1. Title - Decision being documented
2. Status - Proposed/Accepted/Deprecated
3. Context - Why decision was needed
4. Decision - What was decided
5. Alternatives - Options considered with pros/cons
6. Consequences - Trade-offs (positive AND negative)

Checklist:

• Context explains WHY decision was needed?
• Alternatives considered documented?
• Trade-offs clearly stated?
• Consequences (good AND bad) listed?

Guidelines: references/adr-guidelines.md Template: examples/explanation-adr-template.md

Process: Choosing the Right Type

Step 1: Identify the Reader

Who is blocked without this doc?

• New user → Tutorial or README
• Developer doing task → How-to
• Developer looking up info → Reference
• Anyone asking "why" → Explanation

Step 2: Identify the Need

What do they need?

• Learn → Tutorial
• Do → How-to
• Know → Reference
• Understand → Explanation

Step 3: Get Guidelines and Template

1. Consult the guidelines file for rules and tips
2. Use the template file as a starting point

Step 4: Verify

Use the checklist for that doc type.

Anti-Patterns

• Super-documents: Mixing all types in one doc
• Tutorial as Reference: Exhaustive details in learning context
• Reference without verification: Claims not traced to code
• Explanation without context: WHY without background
• How-to with too much explanation: Should be direct
• "Next Steps" instead of "Need Help?": Less actionable

File Structure

documentation-standards/
├── SKILL.md                    # This file - overview and checklists
├── references/                 # Guidelines and rules for each doc type
│   ├── quickstart-guidelines.md
│   ├── contributing-guidelines.md
│   ├── readme-guidelines.md
│   ├── api-docs-guidelines.md
│   ├── tutorial-guidelines.md
│   ├── howto-guidelines.md
│   ├── reference-guidelines.md
│   └── adr-guidelines.md
└── examples/                   # Concrete templates and working samples
    ├── quickstart-template.md
    ├── contributing-template.md
    ├── readme-root-template.md
    ├── readme-module-template.md
    ├── api-docs-template.md
    ├── tutorial-template.md
    ├── howto-template.md
    ├── reference-docs-template.md
    ├── explanation-adr-template.md
    ├── good-readme.md          # Working example
    ├── good-api-doc.md         # Working example
    └── good-adr.md             # Working example

All documentation should be accurate, minimal, and serve a single Diataxis purpose.