# Documentation

> Documentation best practices and templates. Use when creating or improving technical documentation.

- Skill: `saolalab/documentation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add saolalab/documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/saolalab/documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: saolalab (https://skillmd.com/u/saolalab)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/saolalab/documentation

---


# Documentation

## Content Types (Diátaxis)

| Type | Purpose | User Need |
|------|---------|-----------|
| Tutorial | Learning | "Show me how" |
| How-to | Tasks | "Help me do X" |
| Reference | Information | "What are the details?" |
| Explanation | Understanding | "Help me understand" |

## Tutorial Template

```markdown
# [Title]: Getting Started with [Feature]

## What You'll Learn
- Skill 1
- Skill 2

## Prerequisites
- Requirement 1
- Requirement 2

## Steps

### Step 1: [Action]
[Explanation]

```code
example
```

### Step 2: [Action]
[Explanation]

## Next Steps
- [Link to related tutorial]
- [Link to reference]
```

## How-to Template

```markdown
# How to [Task]

## Overview
Brief description of what this guide covers.

## Prerequisites
- Requirement 1

## Steps

1. **Do this first**
   
   [Explanation if needed]
   
2. **Then do this**
   
   ```code
   example
   ```

## Troubleshooting

### Common Issue
Solution to common issue.

## Related
- [Link to related content]
```

## Writing Guidelines

### Clarity
- Use active voice
- Keep sentences short
- One idea per paragraph
- Use consistent terminology

### Structure
- Lead with the most important info
- Use headings for scanability
- Include code examples
- Add visual aids

### Accessibility
- Use descriptive link text
- Add alt text to images
- Ensure proper heading hierarchy
- Consider screen readers

## Documentation Review Checklist

- [ ] Technically accurate
- [ ] Clear and concise
- [ ] Follows style guide
- [ ] Code examples tested
- [ ] Links working
- [ ] Images have alt text