How-To Documentation Skill

This skill provides patterns for writing effective How-To guides in documentation. How-To guides are task-oriented content for users who have a specific goal in mind.

Purpose & Audience

Target readers:

• Users with a specific goal they want to accomplish
• Assumes some familiarity with the product (not complete beginners)
• Looking for practical, actionable steps
• Want to get things done, not learn concepts

How-To guides are NOT:

• Tutorials (which teach through exploration)
• Explanations (which provide understanding)
• Reference docs (which describe the system)

How-To Guide Template

Use this structure for all how-to guides:

---
title: "How to [achieve specific goal]"
description: "Learn how to [goal] using [product/feature]"
---

# How to [Goal]

Brief intro (1-2 sentences): what you'll accomplish and why it's useful.

## Prerequisites

- [What user needs before starting]
- [Required access, tools, or setup]
- [Any prior knowledge assumed]

## Steps

### 1. [Action verb] the [thing]

[Clear instruction with expected outcome]

<Note>
[Optional tip or important context]
</Note>

### 2. [Next action]

[Continue with clear, single-action steps]

```bash
# Example command or code if needed

3. [Continue numbering]

[Each step should be one discrete action]

Verify it worked

[How to confirm success - what should user see/experience?]

Troubleshooting

<AccordionGroup> <Accordion title="[Common issue 1]"> [Solution or workaround] </Accordion> <Accordion title="[Common issue 2]"> [Solution or workaround] </Accordion> </AccordionGroup>

Next steps

• [Related how-to guide 1]
• [Related how-to guide 2]
• [Deeper dive reference doc]

## Writing Principles

### Title Conventions

- **Always start with "How to"** - makes the goal immediately clear
- Use active verbs: "How to configure...", "How to deploy...", "How to migrate..."
- Be specific: "How to add SSO authentication" not "How to set up auth"

### Step Structure

1. **One action per step** - if you write "and", consider splitting
2. **Start with action verbs**: Click, Navigate, Enter, Select, Run, Create
3. **Show expected outcomes** after key steps:
   ```markdown
   ### 3. Save the configuration

   Click **Save**. You should see a success message: "Configuration updated."

Minimize Context

• Don't explain why things work - just show how to do them
• Link to explanations for users who want deeper understanding
• Keep each step focused on the immediate action

User Perspective

Write from the user's perspective, not the product's:

Avoid (product-centric)	Prefer (user-centric)
"The API accepts..."	"Send a request to..."
"The system will..."	"You'll see..."
"This feature allows..."	"You can now..."

Prerequisites Section

Be explicit about what's needed:

## Prerequisites