how-to-guide-writer

What this skill does

# 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 guides
- `docs/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:

```markdown
# 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