Guidelines for creating task-oriented how-to guide documentation. Use when writing content that helps users accomplish specific goals.
This skill provides guidelines for creating how-to guide documentation - task-oriented content in the Diataxis framework.
How-to guides help users accomplish a specific task. The user knows what they want to do and needs practical steps to do it.
"I want to accomplish X."
| Attribute | Description |
|---|---|
| Orientation | Task completion |
| Focus | Practical work |
| Goal |
| Help user achieve a goal |
| Tone | Direct, practical |
Place how-to guides in: docs/guides/
docs/guides/user/ for end-user guidesdocs/guides/developer/ for developer guidesUse this template when creating how-to guide documentation:
# How to [accomplish specific task]
*Last updated: [YYYY-MM-DD]*
## Overview
This guide explains how to [brief description of what this helps you accomplish].
## Prerequisites
Before you begin, ensure you have:
- [Prerequisite 1]
- [Prerequisite 2]
## Steps
### 1. [First action verb phrase]
[Clear, concise instruction]
[Code or command example]
### 2. [Second action verb phrase]
[Clear, concise instruction]
[Code or command example]
### 3. [Third action verb phrase]
[Clear, concise instruction]
> **Note:** [Optional helpful tip or important consideration]
## Verification
To confirm the task completed successfully:
1. [Verification step 1]
2. [Verification step 2]
Expected result:
[What success looks like]
## Troubleshooting
### [Common issue 1]
**Symptom:** [What the user sees or experiences]
**Cause:** [Why this happens]
**Solution:**
[Fix or workaround]
### [Common issue 2]
**Symptom:** [What the user sees]
**Solution:** [How to fix it]
## Related guides
- [Related how-to guide](relative/path.md)
- [Reference documentation](../reference/RELEVANT-REFERENCE.md)
- [Explanation of underlying concept](../architecture/RELEVANT-CONCEPT.md)
Apply this checklist before finalizing any how-to guide documentation.