tutorial-docs

教程文档技能

此技能提供遵循 Diataxis 框架编写有效教程的模式。教程以学习为导向，读者在教师的指导下边做边学。

依赖项： 将此技能与 docs-style 配合使用，以遵循核心写作原则。若要确认内容是否适合写成教程，而非操作指南、参考文档或解释文档，请参阅 docs-style/references/diataxis-compass.md。

目的与受众

目标读者：

• 完全没有经验的初学者
• 想要学习，而非完成某项特定任务的用户
• 希望首次使用产品就能获得成功体验的人
• 能从引导式动手练习中受益的学习者

教程不是：

• 操作指南（帮助完成特定任务）
• 解释文档（帮助理解）
• 参考文档（描述系统）

核心原则（Diataxis 框架）

1. 边做边学，而非只读不做

教程通过行动教学，而不是解释。读者应该时刻都在动手操作。

避免	推荐
“REST API 使用 HTTP 方法来……”	“运行此命令，发起你的第一个 API 调用：”
“身份验证很重要，因为……”	“添加 API 密钥以进行身份验证：”
“仪表板包含几个部分……”	“在仪表板中点击 Create Project。”

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

每次操作后，明确告诉读者应该看到什么。这能确认操作成功并增强信心。

Run the development server:

```bash
npm run dev

你应该会看到：

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

在浏览器中打开 http://localhost:3000。你应该会看到欢迎页面，其中显示“Hello, World!”。

### 3. One Clear Path, Minimize Choices

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

### 4. The Teacher Takes Responsibility

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>

5. 允许重复以建立信心

在略有不同的情境中重复类似操作，有助于巩固所学。不要试图追求效率。

6. 使用第一人称复数进行写作

Diataxis 规定教程应使用“我们”的语气——“在本教程中，我们将构建……”、“现在我们来添加……”、“我们来检查输出。”这能巩固教师与学习者之间的联系：你们正在一起完成这些内容，教师也会为结果负责。仅在描述读者要执行的具体操作时使用直接的第二人称祈使句（“运行此命令”）；整个学习过程则应以“我们”的口吻来引导。

避免	推荐
“你将构建一个仪表板。”	“在本教程中，我们将构建一个仪表板。”
“接下来，配置 API。”	“现在我们来配置 API。”

教程模板

所有教程均使用以下结构：

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

# Build Your First [Thing]

In this tutorial, we'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]

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

## Step 1: [Set up your project]

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

```bash
[command]

你应该会看到：

[expected output]

[简要确认这意味着什么]

第 2 步：[创建你的第一个内容]

[提供清晰指引的下一步操作]

[code to add or modify]

保存文件。你应该会看到[明显的变化]。

[可选提示，用于避免常见错误]

第 3 步：[继续构建]

[继续添加更多步骤，每一步都产生可见输出]

第 4 步：[添加最后一个部分]

[通过最后一步将所有内容整合起来]

现在你应该会看到[最终的可见结果]。

[完成项目的屏幕截图]

你学到了什么

在本教程中，你已经学会：

• [具体技能 1——读者现在可以做到什么]
• [具体技能 2]
• [具体技能 3]

后续步骤

现在你已经有了一个可正常运行的[内容]，可以：

• [教程 2 标题] - 继续学习[下一个学习目标]
• [操作指南] - 学习如何使用你的[内容]来完成[特定任务]
• [概念页面] - 深入了解[概念]

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

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

### Managing Prerequisites

Tutorials are for beginners, so minimize prerequisites:

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

“你应该会看到”模式

这是教程写作中最重要的模式。请经常使用：

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

Run the test:

```bash
npm test

你应该会看到：

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

Tests: 1 passed, 1 total

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

教程组件

截图的 Frame 组件

展示成功后的样子：

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

用于操作步骤的 Steps 组件

用于某个步骤中的编号序列：

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

用于引导的提示框

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

突出显示行的代码

突出显示重要内容：

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

## Example Tutorial

See [references/example-weather-api.md](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.

## Checklist for Tutorials

Before publishing, verify:

- [ ] Title describes what they'll build, not what they'll learn
- [ ] Introduction shows the concrete end result
- [ ] Prerequisites are minimal (beginners don't have much)
- [ ] Every step produces visible output
- [ ] "You should see" appears after each significant action
- [ ] No choices offered - one clear path only
- [ ] No explanations of why things work (save for docs)
- [ ] Potential failures are anticipated with recovery guidance
- [ ] "What you've learned" summarizes concrete skills gained
- [ ] Next steps guide to continued learning
- [ ] Pre-publish gates (below) completed in order—not only self-reviewed

## Pre-publish gates

Run these **in order**. Start the next gate only after the previous **pass** is satisfied.

1. **Draft artifact** — The tutorial exists at a concrete path (file, branch, or CMS location). **Pass:** the artifact opens without guesswork.

2. **Observable outcomes** — **Pass:** every procedural step states what the reader should see next (command output, UI change, or named file)—not only what to do.

3. **Single path** — **Pass:** aside from prerequisite install links, the body does not branch into equivalent alternatives (“npm or yarn…”) unless you split into separate tutorials.

4. **Independent run** — Someone who did not write the draft follows the tutorial from a clean starting point. **Pass:** each step matches its promised outcome; any mismatch is fixed in the doc before publish (see “The Teacher Takes Responsibility” above).

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

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

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

## 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
- **[howto-docs](../howto-docs/SKILL.md)**: How-To guide patterns for task-oriented content
- **[reference-docs](../reference-docs/SKILL.md)**: Reference documentation patterns
- **[explanation-docs](../explanation-docs/SKILL.md)**: Conceptual documentation patterns