tomevault-io How-to Guide Documentation Skill
This skill provides guidelines for creating how-to guide documentation - task-oriented content in the Diataxis framework.
Purpose
How-to guides help users accomplish a specific task. The user knows what they want to do and needs practical steps to do it.
User Need
"I want to accomplish X."
Characteristics
| Attribute | Description |
|---|---|
| Orientation | Task completion |
| Focus | Practical work |
| Goal | Help user achieve a goal |
| Tone | Direct, practical |
Target Directory
Place how-to guides in: docs/guides/
docs/guides/user/for end-user guidesdocs/guides/developer/for developer guides
Writing Guidelines
DO
- Assume the user knows what they want to do
- Focus on practical steps to achieve the goal
- Be flexible and allow for variations
- Include troubleshooting for common issues
- Provide working code examples
- Link to reference docs for details
- Link to explanations for "why" questions
DON'T
- Explain underlying concepts in depth
- Teach or provide learning experiences
- Assume the reader is a beginner
- Include unnecessary background
- Cover every possible variation
Examples of Good How-to Guides
- "How to deploy to production"
- "How to configure authentication"
- "How to migrate from v1 to v2"
- "How to set up local development"
- "How to add a new API endpoint"
Template
Use 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)
Quality Checklist
Apply this checklist before finalizing any how-to guide documentation.
Task Focus
- Title clearly states what task is accomplished
- Focuses on practical steps, not learning
- Assumes user knows what they want to do
- Does not explain underlying concepts in depth
Completeness
- All necessary steps are included
- Prerequisites are listed
- Verification steps confirm success
- Common issues have troubleshooting entries
Practicality
- Steps are actionable
- Code examples work and can be adapted
- Allows for reasonable variations
- Links to reference docs for details
Structure
- Clear, numbered steps
- Each step has a verb-phrase heading
- Logical order of operations
- Troubleshooting section is organized
Clarity
- Instructions are direct and concise
- No unnecessary background information
- Technical terms link to definitions
- Expected results are shown
Maintainability
- No hardcoded values that will change
- Version-specific info is date-stamped
- Related guides are cross-referenced
- Easy to update when things change
Formatting
- Consistent heading structure
- Code blocks have language specified
- Notes/warnings use consistent format
- No broken links
Converted and distributed by TomeVault — claim your Tome and manage your conversions.