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.