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.
apm install @oshankhz/documentation-standards
[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@oshankhz/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.*