documentation-standards

name	documentation-standards
description	This skill should be used when the user asks about "documentation templates", "doc structure", "README format", "API documentation format", "how to write tutorials", "documentation checklist", or when the documentation-writer agent needs templates and workflows for specific documentation types. Provides Diataxis-based templates, checklists, and examples for 7 documentation types.

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

Quadrant	Purpose	Audience	Focus
Tutorial	Learning	Beginners	Hand-holding, confidence building
How-to	Goal completion	Practitioners	Steps to achieve specific goal
Reference	Information	Any level	Exhaustive, accurate lookup
Explanation	Understanding	Curious users	WHY, context, decisions

Documentation Types Overview

Type	Diataxis	When to Use	Guidelines	Template
README (root)	How-to	Project entry point	references/readme-guidelines.md	examples/readme-root-template.md
README (module)	Reference + How-to	Module documentation	references/readme-guidelines.md	examples/readme-module-template.md
Quick Start	How-to	Fast path to working	references/quickstart-guidelines.md	examples/quickstart-template.md
CONTRIBUTING	How-to	Guide contributors	references/contributing-guidelines.md	examples/contributing-template.md
API docs	Reference	Endpoint documentation	references/api-docs-guidelines.md	examples/api-docs-template.md
Tutorial	Tutorial	Onboarding, learning	references/tutorial-guidelines.md	examples/tutorial-template.md
How-to guide	How-to	Specific task completion	references/howto-guidelines.md	examples/howto-template.md
Reference	Reference	Exhaustive information	references/reference-guidelines.md	examples/reference-docs-template.md
Explanation/ADR	Explanation	Architecture decisions	references/adr-guidelines.md	examples/explanation-adr-template.md

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.