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

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

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]

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

[Clear instruction with expected outcome]

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

2. [Next action]

[Continue with clear, single-action steps]

bash

undefined

[Continue with clear, single-action steps]

bash

undefined

Example command or code if needed

undefined

undefined

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]

undefined

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

undefined

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"

始终以"How to"开头 - 让目标一目了然
使用主动动词："How to configure...", "How to deploy...", "How to migrate..."
表述具体："How to add SSO authentication"而非"How to set up auth"

Step Structure

步骤结构

One action per step - if you write "and", consider splitting
Start with action verbs: Click, Navigate, Enter, Select, Run, Create

Show expected outcomes after key steps:

markdown

### 3. Save the configuration

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

每个步骤对应一个操作 - 如果句子中出现"and"，考虑拆分步骤
以主动动词开头：Click（点击）、Navigate（导航至）、Enter（输入）、Select（选择）、Run（运行）、Create（创建）

关键步骤后说明预期结果：

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

从用户视角撰写，而非产品视角：

避免（产品视角）	推荐（用户视角）
"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:

markdown

undefined

明确列出所需条件：

markdown

undefined

Prerequisites

An active account with admin permissions
API key generated from Settings > API
Node.js v18 or later installed
Completed the initial setup guide

undefined

An active account with admin permissions
API key generated from Settings > API
Node.js v18 or later installed
Completed the initial setup guide

undefined

Components for How-To Guides

操作指南组件

Steps Component

步骤组件

For numbered procedures, use a Steps component:

markdown

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

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

markdown

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

markdown

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

bash

yarn add @company/sdk

bash

pnpm add @company/sdk

</CodeGroup> ```

展示不同实现方式时：

markdown

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

bash

yarn add @company/sdk

bash

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>

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:

markdown

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

用于无需打断流程的可选细节：

markdown

<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

操作指南示例

markdown

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

markdown

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

Admin access to your account
A publicly accessible HTTPS endpoint to receive webhooks
Completed the authentication setup

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>

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

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

<AccordionGroup> <Accordion title="Webhook not receiving events"> - Verify your endpoint is publicly accessible - Check that your SSL certificate is valid - Ensure your server responds with 2xx status within 30 seconds </Accordion> <Accordion title="Signature verification failing"> - Confirm you're using the correct signing secret - Check that you're reading the raw request body (not parsed JSON) - See our [signature verification guide](/reference/webhook-signatures) </Accordion> </AccordionGroup>

Next steps

undefined

undefined

Checklist for How-To Guides

操作指南检查清单

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"

用户心态	文档类型	示例
"我想要学习"	教程	"Getting started with our API"（API入门）
"我想要完成X操作"	操作指南	"How to configure SSO"（配置SSO）
"我想要理解原理"	说明文档	"How our caching works"（缓存机制说明）
"我需要查询Y信息"	参考文档	"API endpoint reference"（API端点参考）

howto-docs

Original

Translation

How-To Documentation Skill

操作指南文档撰写技巧

Purpose & Audience

目的与受众

How-To Guide Template

操作指南模板

How to [Goal]

How to [Goal]

Prerequisites

Prerequisites

Steps

Steps

1. [Action verb] the [thing]

1. [Action verb] the [thing]

2. [Next action]

2. [Next action]

Example command or code if needed

Example command or code if needed

3. [Continue numbering]

3. [Continue numbering]

Verify it worked

Verify it worked

Troubleshooting

Troubleshooting

Next steps

Next steps

Writing Principles

撰写原则

Title Conventions

标题规范

Step Structure

步骤结构

Minimize Context

减少冗余背景

User Perspective

用户视角

Prerequisites Section

前置条件部分

Prerequisites

Prerequisites

Components for How-To Guides

操作指南组件

Steps Component

步骤组件

Code Groups for Multiple Options

多选项代码组

Callouts for Important Information

重要信息提示框

Expandable Sections

可展开章节

Example How-To Guide

操作指南示例

How to Set Up Webhook Notifications

How to Set Up Webhook Notifications

Prerequisites

Prerequisites

Steps

Steps

Verify it worked

Verify it worked

Troubleshooting

Troubleshooting

Next steps

Next steps

Checklist for How-To Guides

操作指南检查清单

When to Use How-To vs Other Doc Types

操作指南与其他文档类型的适用场景

Related Skills

相关技巧