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.

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.

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:

markdownCopy code
---
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

Next steps

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

Copy code

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

Prerequisites Section

Be explicit about what's needed:

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

markdownCopy code
<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:

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

bashCopy code
yarn add @company/sdk

bashCopy code
pnpm add @company/sdk

Callouts for Important Information

markdownCopy code
<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:

markdownCopy code
<Expandable title="Advanced options">
  If you need custom configuration, you can also set:
  - `timeout`: Request timeout in milliseconds
  - `retries`: Number of retry attempts
</Expandable>

Example How-To Guide

markdownCopy code
---
title: "How to set up webhook notifications"
description: "Learn how to configure webhooks to receive real-time event notifications"
---

# How to Set Up Webhook Notifications

Configure webhooks to receive instant notifications when events occur in your account. This enables real-time integrations with your existing tools.

## Prerequisites

- Admin access to your account
- A publicly accessible HTTPS endpoint to receive webhooks
- Completed the [authentication setup](/getting-started/auth)

## Steps

<Steps>
  <Step title="Navigate to webhook settings">
    Go to **Settings** > **Integrations** > **Webhooks**.
  </Step>

  <Step title="Add a new webhook endpoint">
    Click **Add Endpoint** and enter your webhook URL:

    ```
    https://your-domain.com/webhooks/receiver
    ```

    <Note>
    Your endpoint must use HTTPS and be publicly accessible.
    </Note>
  </Step>

  <Step title="Select events to subscribe">
    Choose which events should trigger notifications:

    - `user.created` - New user sign up
    - `payment.completed` - Successful payment
    - `subscription.cancelled` - Subscription ended

    Select at least one event to continue.
  </Step>

  <Step title="Save and get your signing secret">
    Click **Create Webhook**. Copy the signing secret shown - you'll need this to verify webhook authenticity.

    <Warning>
    Store the signing secret securely. It won't be shown again.
    </Warning>
  </Step>
</Steps>

## Verify it worked

Send a test event by clicking **Send Test** next to your webhook. You should receive a POST request at your endpoint with this structure:

```json
{
  "event": "test.webhook",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {}
}

Check your endpoint logs to confirm receipt.

Troubleshooting

Next steps

• How to verify webhook signatures
• Webhook event reference
• How to handle webhook retries

Copy code

## Hard gates (before publishing)

Complete in order. Do not treat the doc as ready until each gate passes.

1. **Goal lock** — Title starts with `How to` and names a specific outcome (verb + object). **Pass:** a reader can state what they will have done after following the guide, in one sentence, without reading the steps.

2. **Prerequisites closed** — Everything required before step 1 is listed (access, tools, versions, prior guides). **Pass:** you cannot name a blocker that belongs in Prerequisites but is missing from the list.

3. **Steps are atomic** — Each numbered step is one primary action; split if you would join with “and then” for unrelated actions. **Pass:** each step has a clear next action; risky steps (save, deploy, delete) state what the user should see after.

4. **Success is observable** — The “Verify it worked” section names concrete signals (UI text, exit code, HTTP status, file path, log line). **Pass:** the reader can confirm success without interpreting vague “it works.”

5. **Checklist complete** — Run the checklist below; every item is honestly yes or the guide is not ready to ship. **Pass:** all boxes checked.

## Checklist for How-To Guides

Before publishing, verify:

- [ ] Title starts with "How to" and describes a specific goal
- [ ] Prerequisites section lists all requirements
- [ ] Each step is a single, clear action
- [ ] Action verbs start each step (Click, Enter, Select, Run)
- [ ] Expected outcomes shown after key steps
- [ ] Verification section explains how to confirm success
- [ ] Troubleshooting covers common issues
- [ ] Next steps link to related content
- [ ] No unnecessary explanations - links to concepts instead
- [ ] Written from user perspective, not product perspective

## When to Use How-To vs Other Doc Types

| User's mindset | Doc type | Example |
|---------------|----------|---------|
| "I want to learn" | Tutorial | "Getting started with our API" |
| "I want to do X" | How-To | "How to configure SSO" |
| "I want to understand" | Explanation | "How our caching works" |
| "I need to look up Y" | Reference | "API endpoint reference" |

For the full compass procedure and the other type distinctions, see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

## Related Skills

- **[docs-style](../docs-style/SKILL.md)**: Core writing conventions and components
- **[Diataxis compass](../docs-style/references/diataxis-compass.md)**: Type selection, the 2×2 map, and the quality model
- **[tutorial-docs](../tutorial-docs/SKILL.md)**: Tutorial patterns for learning-oriented content
- **[reference-docs](../reference-docs/SKILL.md)**: Reference documentation patterns
- **[explanation-docs](../explanation-docs/SKILL.md)**: Conceptual documentation patterns