tutorial-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tutorial Documentation Skill

教程文档撰写技能

This skill provides patterns for writing effective tutorials following the Diataxis framework. Tutorials are learning-oriented content where the reader learns by doing under the guidance of a teacher.

本技能提供遵循Diataxis框架的有效教程撰写模式。教程是以学习为导向的内容，读者在“老师”的指导下通过实践进行学习。

Purpose & Audience

目标与受众

Target readers:

Complete beginners with no prior experience
Users who want to learn, not accomplish a specific task
People who need a successful first experience with the product
Learners who benefit from guided, hands-on practice

Tutorials are NOT:

How-To guides (which help accomplish specific tasks)
Explanations (which provide understanding)
Reference docs (which describe the system)

目标读者：

无任何相关经验的纯新手
想要学习而非完成特定任务的用户
需要首次成功使用产品的人群
能从指导性实操练习中获益的学习者

教程不是：

操作指南（帮助完成特定任务）
讲解文档（提供概念理解）
参考文档（描述系统细节）

Core Principles (Diataxis Framework)

核心原则（Diataxis框架）

1. Learn by Doing, Not by Reading

1. 做中学，而非读中学

Tutorials teach through action, not explanation. The reader should be doing something at every moment.

Avoid	Prefer
"REST APIs use HTTP methods to..."	"Run this command to make your first API call:"
"Authentication is important because..."	"Add your API key to authenticate:"
"The dashboard contains several sections..."	"Click Create Project in the dashboard."

教程通过行动而非讲解进行教学。读者应时刻都在进行操作。

避免写法	推荐写法
"REST APIs use HTTP methods to..."	"运行以下命令发起你的首次API调用："
"Authentication is important because..."	"添加你的API密钥进行身份验证："
"The dashboard contains several sections..."	"点击控制台中的【创建项目】按钮。"

2. Deliver Visible Results at Every Step

2. 每一步都呈现可见结果

After each action, tell readers exactly what they should see. This confirms success and builds confidence.

markdown

Run the development server:

```bash
npm run dev

You should see:

> Local: http://localhost:3000
> Ready in 500ms

Open http://localhost:3000 in your browser. You should see a welcome page with "Hello, World!" displayed.

undefined

每完成一个操作后，明确告知读者应该看到的内容。这能确认操作成功并建立信心。

markdown

Run the development server:

```bash
npm run dev

You should see:

> Local: http://localhost:3000
> Ready in 500ms

Open http://localhost:3000 in your browser. You should see a welcome page with "Hello, World!" displayed.

undefined

3. One Clear Path, Minimize Choices

3. 单一清晰路径，最小化选择

Tutorials should not offer alternatives. Pick one way and guide the reader through it completely.

Avoid	Prefer
"You can use npm, yarn, or pnpm..."	"Install the dependencies:"
"There are several ways to configure..."	"Create a config file:"
"Optionally, you might want to..."	[Omit optional steps entirely]

教程不应提供替代方案。选择一种方式，全程引导读者完成。

避免写法	推荐写法
"You can use npm, yarn, or pnpm..."	"安装依赖："
"There are several ways to configure..."	"创建配置文件："
"Optionally, you might want to..."	[完全省略可选步骤]

4. The Teacher Takes Responsibility

4. 撰写者承担全部责任

If the reader fails, the tutorial failed. Anticipate problems and prevent them. Never blame the reader.

markdown

<Warning>
Make sure you're in the project directory before running this command.
If you see "command not found", return to Step 2 to verify the installation.
</Warning>

如果读者操作失败，说明教程存在问题。要预判问题并提前规避，切勿指责读者。

markdown

<Warning>
Make sure you're in the project directory before running this command.
If you see "command not found", return to Step 2 to verify the installation.
</Warning>

5. Permit Repetition to Build Confidence

5. 允许重复操作以建立信心

Repeating similar actions in slightly different contexts helps cement learning. Don't try to be efficient.

在略有不同的场景中重复类似操作有助于巩固学习成果，无需追求效率。

Tutorial Template

教程模板

Use this structure for all tutorials:

markdown

---
title: "Build your first [thing]"
description: "Learn the basics of [product] by building a working [thing]"
---

所有教程都可使用以下结构：

markdown

---
title: "Build your first [thing]"
description: "Learn the basics of [product] by building a working [thing]"
---

Build Your First [Thing]

In this tutorial, you'll build a [concrete deliverable]. By the end, you'll have a working [thing] that [does something visible].

<Note> This tutorial takes approximately [X] minutes to complete. </Note>

In this tutorial, you'll build a [concrete deliverable]. By the end, you'll have a working [thing] that [does something visible].

<Note> This tutorial takes approximately [X] minutes to complete. </Note>

What you'll build

[Screenshot or diagram of the end result]

A [brief description of the concrete deliverable] that:

[Visible capability 1]
[Visible capability 2]
[Visible capability 3]

[Screenshot or diagram of the end result]

A [brief description of the concrete deliverable] that:

[Visible capability 1]
[Visible capability 2]
[Visible capability 3]

Prerequisites

Before starting, make sure you have:

[Minimal requirement 1 - link to install guide if needed]
[Minimal requirement 2]

<Tip> New to [prerequisite]? [Link to external resource] has a quick setup guide. </Tip>

Before starting, make sure you have:

[Minimal requirement 1 - link to install guide if needed]
[Minimal requirement 2]

<Tip> New to [prerequisite]? [Link to external resource] has a quick setup guide. </Tip>

Step 1: [Set up your project]

[First action - always start with something that produces visible output]

bash

[command]

You should see:

[expected output]

[Brief confirmation of what this means]

[First action - always start with something that produces visible output]

bash

[command]

You should see:

[expected output]

[Brief confirmation of what this means]

Step 2: [Create your first thing]

[Next action with clear instruction]

code

[code to add or modify]

Save the file. You should see [visible change].

<Note> [Optional tip to prevent common mistakes] </Note>

[Next action with clear instruction]

code

[code to add or modify]

Save the file. You should see [visible change].

<Note> [Optional tip to prevent common mistakes] </Note>

Step 3: [Continue building]

[Continue with more steps, each producing visible output]

Step 4: [Add the final piece]

[Bring it together with a final step]

You should now see [final visible result].

[Screenshot of completed project]

[Bring it together with a final step]

You should now see [final visible result].

[Screenshot of completed project]

What you've learned

In this tutorial, you:

[Concrete skill 1 - what they can now do]
[Concrete skill 2]
[Concrete skill 3]

In this tutorial, you:

[Concrete skill 1 - what they can now do]
[Concrete skill 2]
[Concrete skill 3]

Next steps

Now that you have a working [thing], you can:

[Tutorial 2 title] - Continue learning by [next learning goal]
[How-to guide] - Learn how to [specific task] with your [thing]
[Concepts page] - Understand [concept] in more depth

undefined

Now that you have a working [thing], you can:

[Tutorial 2 title] - Continue learning by [next learning goal]
[How-to guide] - Learn how to [specific task] with your [thing]
[Concepts page] - Understand [concept] in more depth

undefined

Writing Principles

撰写原则

Title Conventions

标题规范

Start with action outcomes: "Build your first...", "Create a...", "Deploy your..."
Focus on what they'll make, not what they'll learn
Be concrete: "Build a chat application" not "Learn about real-time messaging"

以行动成果开头：例如“构建你的第一个……”、“创建一个……”、“部署你的……”
聚焦于读者将制作的内容，而非将学习的知识
内容要具体：比如“构建聊天应用”而非“学习实时消息传递”

Step Structure

步骤结构

Lead with the action - don't explain before doing
Show exactly what to type or click - no ambiguity
Confirm success after every step - "You should see..."
Keep steps small - one visible change per step

以行动为先导 - 先操作再解释
明确展示输入或点击内容 - 无歧义
每步操作后确认成功 - 使用“你应该看到……”
步骤拆分要小 - 每步只产生一个可见变化

Managing Prerequisites

前置条件管理

Tutorials are for beginners, so minimize prerequisites:

markdown

undefined

教程面向新手，因此要最小化前置条件：

markdown

undefined

Prerequisites

A computer with macOS, Windows, or Linux
A text editor (we recommend VS Code)
15 minutes of time

<Tip> You don't need any programming experience. This tutorial explains everything as we go. </Tip> ```

A computer with macOS, Windows, or Linux
A text editor (we recommend VS Code)
15 minutes of time

<Tip> You don't need any programming experience. This tutorial explains everything as we go. </Tip> ```

The "You should see" Pattern

“你应该看到”模式

This is the most important pattern in tutorial writing. Use it constantly:

markdown

Click **Save**. You should see a green checkmark appear next to the filename.

Run the test:

```bash
npm test

You should see:

PASS  src/app.test.js
  ✓ renders welcome message (23ms)

Tests: 1 passed, 1 total

undefined

这是教程撰写中最重要的模式，请频繁使用：

markdown

Click **Save**. You should see a green checkmark appear next to the filename.

Run the test:

```bash
npm test

You should see:

PASS  src/app.test.js
  ✓ renders welcome message (23ms)

Tests: 1 passed, 1 total

undefined

Handling Errors Gracefully

优雅处理错误

Anticipate failures and guide readers back on track:

markdown

<Warning>
If you see "Module not found", make sure you saved the file from Step 2.
Return to Step 2 and verify the import statement matches exactly.
</Warning>

预判可能的失败并引导读者回到正轨：

markdown

<Warning>
If you see "Module not found", make sure you saved the file from Step 2.
Return to Step 2 and verify the import statement matches exactly.
</Warning>

Components for Tutorials

教程组件

Frame Component for Screenshots

截图框架组件

Show what success looks like:

markdown

<Frame caption="Your completed dashboard should look like this">
  ![Dashboard screenshot](/images/tutorial-dashboard.png)
</Frame>

展示成功后的效果：

markdown

<Frame caption="Your completed dashboard should look like this">
  ![Dashboard screenshot](/images/tutorial-dashboard.png)
</Frame>

Steps Component for Procedures

步骤序列组件

For numbered sequences within a step:

markdown

<Steps>
  <Step title="Open the settings panel">
    Click the gear icon in the top right corner.
  </Step>
  <Step title="Find the API section">
    Scroll down to **Developer Settings**.
  </Step>
  <Step title="Generate a key">
    Click **Create New Key** and copy the value shown.
  </Step>
</Steps>

用于步骤内的编号序列：

markdown

<Steps>
  <Step title="Open the settings panel">
    Click the gear icon in the top right corner.
  </Step>
  <Step title="Find the API section">
    Scroll down to **Developer Settings**.
  </Step>
  <Step title="Generate a key">
    Click **Create New Key** and copy the value shown.
  </Step>
</Steps>

Callouts for Guidance

指导性提示框

markdown

<Note>
Don't worry if the colors look different on your screen.
We'll customize the theme in the next step.
</Note>

<Warning>
Make sure to save the file before continuing.
The next step won't work without this change.
</Warning>

<Tip>
You can press Cmd+S (Mac) or Ctrl+S (Windows) to save quickly.
</Tip>

markdown

<Note>
Don't worry if the colors look different on your screen.
We'll customize the theme in the next step.
</Note>

<Warning>
Make sure to save the file before continuing.
The next step won't work without this change.
</Warning>

<Tip>
You can press Cmd+S (Mac) or Ctrl+S (Windows) to save quickly.
</Tip>

Code with Highlighted Lines

高亮代码行

Draw attention to what matters:

markdown

```javascript {3-4}
function App() {
  return (
    <h1>Hello, World!</h1>
    <p>Welcome to your first app.</p>
  );
}

undefined

markdown

```javascript {3-4}
function App() {
  return (
    <h1>Hello, World!</h1>
    <p>Welcome to your first app.</p>
  );
}

undefined

Example Tutorial

示例教程

See references/example-weather-api.md for a complete example tutorial demonstrating all principles above. The example builds a weather dashboard that fetches real API data.

查看references/example-weather-api.md获取完整示例教程，该示例展示了上述所有原则，构建了一个获取真实API数据的天气控制台。

Checklist for Tutorials

教程检查清单

When to Use Tutorial vs Other Doc Types

何时使用教程而非其他文档类型

User's mindset	Doc type	Example
"I want to learn"	Tutorial	"Build your first chatbot"
"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"

用户心态	文档类型	示例
"我想学习"	教程	"构建你的第一个聊天机器人"
"我想完成X任务"	操作指南	"如何配置SSO"
"我想了解原理"	讲解文档	"我们的缓存机制如何工作"
"我需要查询Y内容"	参考文档	"API端点参考"

Tutorial vs How-To: Key Differences

教程与操作指南的核心区别

Aspect	Tutorial	How-To
Purpose	Learning through doing	Accomplishing a specific task
Audience	Complete beginners	Users with some experience
Structure	Linear journey with one path	Steps to achieve a goal
Choices	None - one prescribed way	May show alternatives
Explanations	Minimal - action over theory	Minimal - focus on steps
Success	Reader learns and gains confidence	Reader completes their task
Length	Longer, more hand-holding	Shorter, more direct

维度	教程	操作指南
目标	通过实践学习	完成特定任务
受众	纯新手	有一定经验的用户
结构	线性流程，单一路径	达成目标的步骤
选择	无，只有指定路径	可能提供替代方案
解释	极简，重操作轻理论	极简，聚焦步骤
成功标准	读者学到知识并建立信心	读者完成任务
长度	较长，全程引导	较短，直接高效

tutorial-docs

Original

Translation

Tutorial Documentation Skill

教程文档撰写技能

Purpose & Audience

目标与受众

Core Principles (Diataxis Framework)

核心原则（Diataxis框架）

1. Learn by Doing, Not by Reading

1. 做中学，而非读中学

2. Deliver Visible Results at Every Step

2. 每一步都呈现可见结果

3. One Clear Path, Minimize Choices

3. 单一清晰路径，最小化选择

4. The Teacher Takes Responsibility

4. 撰写者承担全部责任

5. Permit Repetition to Build Confidence

5. 允许重复操作以建立信心

Tutorial Template

教程模板

Build Your First [Thing]

Build Your First [Thing]

What you'll build

What you'll build

Prerequisites

Prerequisites

Step 1: [Set up your project]

Step 1: [Set up your project]

Step 2: [Create your first thing]

Step 2: [Create your first thing]

Step 3: [Continue building]

Step 3: [Continue building]

Step 4: [Add the final piece]

Step 4: [Add the final piece]

What you've learned

What you've learned

Next steps

Next steps

Writing Principles

撰写原则

Title Conventions

标题规范

Step Structure

步骤结构

Managing Prerequisites

前置条件管理

Prerequisites

Prerequisites

The "You should see" Pattern

“你应该看到”模式

Handling Errors Gracefully

优雅处理错误

Components for Tutorials

教程组件

Frame Component for Screenshots

截图框架组件

Steps Component for Procedures

步骤序列组件

Callouts for Guidance

指导性提示框

Code with Highlighted Lines

高亮代码行

Example Tutorial

示例教程

Checklist for Tutorials

教程检查清单

When to Use Tutorial vs Other Doc Types

何时使用教程而非其他文档类型

Tutorial vs How-To: Key Differences

教程与操作指南的核心区别

Related Skills

相关技能