howto-docs

# 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:

```markdown
---
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" no