/howto-docs

name: howto-docs
description: "How-To guide patterns for documentation - task-oriented guides for users with specific goals. Use when writing a how-to/howto guide, task guide, procedural guide, step-by-step guide, or how-to documentation. Builds on the docs-style core writing principles."
user-invocable: false

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.

**Dependency:** Use this skill with `docs-style` for core writing principles. To confirm a how-to is the right type — rather than a tutorial, reference, or explanation — see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

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

Use Conditional Imperatives and Address the Real World

Unlike a tutorial — which controls a single, guaranteed path — a how-to meets the user in the messy real world. Diataxis frames steps as **conditional imperatives**: "*If you want X, do Y.*" This respects that the reader arrives with their own context and goal.

• **Branch where reality branches.** When the right action depends on the user's situation, say so ("If you deploy to staging, set `ENV=staging`; for production, use…") rather than pretending one path fits all.
• **Prepare for the unexpected.** Note the failure modes and detours a competent user will actually hit (the Troubleshooting section is where these live).
• **Omit the unnecessary.** A how-to aims at practical usability, not completeness. Leave out anything that doesn't move the reader toward the goal; link to Reference for exhaustive detail.

Name the Guide by What It Achieves

Titles state exactly what the guide accomplishes, using the user's goal: "How to integrate Stripe payments," not "Payments" or "The Stripe module." If you cannot name the concrete outcome, the scope is not yet clear enough to write.

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

- An active account with admin permissions
- API key generated from Settings > API
- Node.js v18 or later installed
- Completed the [initial setup guide](/getting-started)

Components for How-To Guides

Steps Component

For numbered procedures, use a Steps component:

<Steps>
  <Step title="Create a new project">
    Navigate to the dashboard and click **New Project**.
  </Step>
  <Step title="Configure settings">
    Enter your project name and select a region.
  </Step>
  <Step title="Deploy">
    Click **Deploy** to launch your project.
  </Step>
</Steps>

Code Groups for Multiple Options

When showing different approaches:

<CodeGroup>
```bash npm
npm install @company/sdk

yarn add @company/sdk

pnpm add @company/sdk

</CodeGroup>

### Callouts for Important Information

```markdown
<Warning>
This action cannot be undone. Make sure to backup your data first.
</Warning>

<Note>
This step may take 2-3 minutes to complete.
</Note>

<Tip>
You can also use keyboard shortcut Cmd+K for faster navigation.
</Tip>

Expandable Sections

For optional details that shouldn't interrupt flow:

<Expandable title="Advanced options">
  If you need custom configuration, you ca