howto-docs

操作指南文档技能

此技能提供编写有效操作指南文档的模式。操作指南面向有明确目标的用户，内容以任务为导向。

依赖项： 将此技能与 docs-style 一起使用，以遵循核心写作原则。要确认操作指南是合适的文档类型，而不是教程、参考文档或说明，请参阅 docs-style/references/diataxis-compass.md。

目的与受众

目标读者：

• 有明确目标并希望达成的用户
• 假设读者对产品有一定了解（并非完全的初学者）
• 希望获得实用、可执行的步骤
• 想要完成任务，而不是学习概念

操作指南不是：

• 教程（通过探索来教学）
• 说明（帮助读者理解）
• 参考文档（描述系统）

操作指南模板

所有操作指南都使用以下结构：

---
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. [继续编号]

[每个步骤都应是一项独立操作]

验证是否成功

[如何确认成功——用户应该看到或体验到什么？]

故障排除

[解决方案或变通方法] [解决方案或变通方法]

后续步骤

• [相关操作指南 1]
• [相关操作指南 2]
• [深入了解的参考文档]

## 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."

尽量精简上下文

• 不要解释事情为何有效——只展示如何操作
• 为希望深入了解的用户链接到说明文档
• 让每个步骤都专注于当前要执行的操作

使用条件式祈使句并贴近现实

教程会限定一条确定的路径，而操作指南则要面对纷繁复杂的现实情况。Diataxis 将步骤描述为条件式祈使句：“如果你想实现 X，就执行 Y。”这能尊重读者各自的背景和目标。

• 按现实情况分支。 当正确的操作取决于用户的情况时，要明确说明（“如果部署到预发布环境，请设置 ENV=staging；如果部署到生产环境，请使用……”），不要假设一条路径适用于所有人。
• 为意外情况做好准备。 指出有经验的用户实际可能遇到的失败情况和绕行方案（这些内容应放在“故障排除”部分）。
• 省略不必要的内容。 操作指南追求实用，而非面面俱到。省略所有无助于读者达成目标的内容；详尽细节请链接到参考文档。

根据指南的目标命名

标题应直接说明指南能实现什么，并以用户目标为中心：“如何集成 Stripe 支付”，而不是“支付”或“Stripe 模块”。如果无法说清具体结果，说明范围还不够明确，暂时无法动笔。

用户视角

从用户的角度写作，而不是从产品的角度：

避免（以产品为中心）	推荐（以用户为中心）
“API 接受……”	“发送请求……”
“系统将……”	“你将看到……”
“此功能允许……”	“现在你可以……”

前置条件部分

明确说明所需条件：

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

操作指南的组成部分

步骤组件

对于编号流程，请使用 Steps 组件：

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

多种选项的代码组

展示不同方法时：

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

yarn add @company/sdk

pnpm add @company/sdk

```

Callouts for Important Information

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

操作指南示例

---
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": {}
}

检查端点日志，确认是否已收到请求。

故障排除

- 确认你的端点可从公网访问 - 检查 SSL 证书是否有效 - 确保你的服务在 30 秒内返回 2xx 状态码 - 确认你使用的是正确的签名密钥 - 检查你读取的是原始请求正文（而非解析后的 JSON） - 请参阅我们的[签名验证指南](/reference/webhook-signatures)

后续步骤

• 如何验证 Webhook 签名
• Webhook 事件参考
• 如何处理 Webhook 重试

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