Back to Details

howto-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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]

How to [Goal]

Brief intro (1-2 sentences): what you'll accomplish and why it's useful.
Brief intro (1-2 sentences): what you'll accomplish and why it's useful.

Prerequisites

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

Steps

1. [Action verb] the [thing]

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]

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

Example command or code if needed

undefined
undefined

3. [Continue numbering]

3. [Continue numbering]

[Each step should be one discrete action]
[Each step should be one discrete action]

Verify it worked

Verify it worked

[How to confirm success - what should user see/experience?]
[How to confirm success - what should user see/experience?]

Troubleshooting

Troubleshooting

<AccordionGroup> <Accordion title="[Common issue 1]"> [Solution or workaround] </Accordion> <Accordion title="[Common issue 2]"> [Solution or workaround] </Accordion> </AccordionGroup>
<AccordionGroup> <Accordion title="[Common issue 1]"> [Solution or workaround] </Accordion> <Accordion title="[Common issue 2]"> [Solution or workaround] </Accordion> </AccordionGroup>

Next steps

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

步骤结构

  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."
  1. 每个步骤对应一个操作 - 如果句子中出现"and"，考虑拆分步骤
  2. 以主动动词开头：Click（点击）、Navigate（导航至）、Enter（输入）、Select（选择）、Run（运行）、Create（创建）
  3. 关键步骤后说明预期结果：
    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

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

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.
Configure webhooks to receive instant notifications when events occur in your account. This enables real-time integrations with your existing tools.

Prerequisites

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

<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

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

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

Next steps

undefined
undefined

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
发布前，请确认：
  • 标题以"How to"开头，且描述了具体目标
  • 前置条件部分列出了所有要求
  • 每个步骤是单一、清晰的操作
  • 每个步骤以主动动词开头（Click、Enter、Select、Run等）
  • 关键步骤后说明了预期结果
  • 验证部分解释了如何确认操作成功
  • 故障排除覆盖了常见问题
  • 后续步骤链接到相关内容
  • 无冗余解释，相关概念链接至对应文档
  • 从用户视角撰写，而非产品视角

When to Use How-To vs Other Doc Types

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

User's mindsetDoc typeExample
"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端点参考）

Related Skills

相关技巧

  • docs-style: Core writing conventions and components
  • tutorial-docs: Tutorial patterns for learning-oriented content
  • reference-docs: Reference documentation patterns
  • explanation-docs: Conceptual documentation patterns
  • docs-style: 核心写作规范与组件
  • tutorial-docs: 面向学习的教程模式
  • reference-docs: 参考文档模式
  • explanation-docs: 概念性文档模式