Tutorial 类型文档撰写标准
定义
Tutorial 是学习导向的文档，通过引导式练习帮助新手获得基础技能和初步体验。
核心特征
| 特征 | 要求 | 对比其他类型 |
|---|---|---|
| 目的 | 建立初始技能和信心 | Reference: 提供查询 Explanation: 建立理解 How-to: 解决问题 |
| 阅读方式 | 跟随练习，边学边做 | Reference: 跳跃查找 Explanation: 顺序阅读 How-to: 按需查找 |
| 内容组织 | 精心设计的学习路径 | Reference: 结构化信息 Explanation: 逻辑叙述 How-to: 任务步骤 |
| 语言风格 | 友好鼓励，耐心引导 | Reference: 技术精确 Explanation: 通俗易懂 How-to: 简洁指令 |
| 前置条件 | 零基础，最小化假设 | Reference: 假设已了解 Explanation: 假设不了解 How-to: 假设有背景 |
适用场景
应该写 Tutorial
- 新手入门指南
- 快速上手教程
- 功能初体验
- 基础技能培训
- 环境搭建指导
- Hello World 示例
不该写 Tutorial
- 高级技巧 → How-to
- 完整功能说明 → Reference
- 理论原理 → Explanation
- 复杂任务 → How-to
- 所有功能展示 → Reference
必要元素
| 元素 | 说明 | 必需性 |
|---|---|---|
| 学习目标 | 明确将掌握什么 | 必需 |
| 预计时间 | 完成需要多久 | 必需 |
| 环境准备 | 最小化的前置要求 | 必需 |
| 渐进步骤 | 从简到难的练习 | 必需 |
| 成功体验 | 每步都有正向反馈 | 必需 |
| 总结回顾 | 强化学到的内容 | 必需 |
| 下一步建议 | 指引继续学习方向 | 建议 |
结构规范
标准结构
markdown
# [技术/工具] 快速入门
## 学习目标
完成本教程后，你将能够：
- 目标1
- 目标2
- 目标3
## 准备工作
- 需要安装...（5分钟）
- 基础知识：无需编程经验
## 第一步：[建立直观认识]
让我们先看看最终效果...
[操作说明]
[预期结果]
## 第二步：[动手尝试简单任务]
现在轮到你了...
[操作说明]
[成功标志]
## 第三步：[稍微增加复杂度]
让我们尝试更多...
[操作说明]
[可能的问题和解决]
## 总结
恭喜！你已经学会了：
✅ 技能点1
✅ 技能点2
✅ 技能点3
## 下一步
- 深入学习：[链接]
- 实践项目：[链接]设计原则
- 循序渐进 - 难度逐步提升，不能跳跃
- 即时反馈 - 每步都要看到结果
- 容错设计 - 预见并处理可能的错误
- 重复强化 - 核心概念多次练习
- 保持专注 - 不引入无关内容
写作要求
语言规范
| 要求 | 说明 | 示例 |
|---|---|---|
| 鼓励性语言 | 给予信心和动力 | ✅ "很好！现在让我们..." ❌ "你必须..." |
| 清晰指令 | 精确说明每个动作 | ✅ "点击右上角的蓝色按钮" ❌ "点击按钮" |
| 预期管理 | 告知将发生什么 | ✅ "稍等3秒，会看到..." ❌ "等待加载" |
| 错误友好 | 错误是学习机会 | ✅ "如果出现错误，说明..." ❌ "不要出错" |
练习设计
- 最小可行练习 - 用最少的步骤达到效果
- 一次一个概念 - 不要同时引入多个新概念
- 可重复执行 - 练习可以反复尝试
- 明确的结束 - 清楚何时完成
示例要求
bash
# 示例必须：
# 1. 完整可运行
# 2. 包含具体数值
# 3. 展示预期输出
echo "Hello, Tutorial!"
# 输出：Hello, Tutorial!质量标准
必须满足
- [ ] 30分钟内可完成
- [ ] 零基础可跟随
- [ ] 每步都有明确结果
- [ ] 不超过7个主要步骤
- [ ] 包含成功截图或输出
- [ ] 有具体的学习目标
- [ ] 语言友好鼓励
必须避免
- [ ] 过多理论解释
- [ ] 复杂的环境配置
- [ ] 跳跃式难度提升
- [ ] 模糊的操作指令
- [ ] 过多的选择分支
- [ ] 假设前置知识
- [ ] 负面或威胁性语言
特殊类型
环境搭建型
markdown
## 安装 [工具名]
### Windows
1. 下载安装包：[链接]
2. 双击运行...
3. 验证安装：`command --version`
### macOS
1. 使用 Homebrew：`brew install...`
2. 验证安装...
### 常见问题
- 问题1：[解决方案]
- 问题2：[解决方案]功能体验型
markdown
## 体验 [功能名]
### 准备示例数据
[提供或创建简单数据]
### 基础操作
1. 最简单的使用...
2. 看到效果了吗？
### 进阶一点
1. 现在加入参数...
2. 注意变化...
### 自己试试
挑战：能不能...？
提示：使用...概念学习型
markdown
## 理解 [概念名]
### 直观体验
1. 先看这个例子...
2. 发现规律了吗？
### 动手验证
1. 修改这里...
2. 观察结果...
### 深入一步
1. 如果这样...
2. 结果会...
### 总结规律
通过实践，我们发现：
- 规律1
- 规律2与其他类型的关系
| 关系类型 | 说明 | 示例 |
|---|---|---|
| 后续 How-to | 学会基础后解决具体问题 | "更多任务见 How-to" |
| 深入 Explanation | 理解背后的原理 | "原理解释见..." |
| 查询 Reference | 完整功能参考 | "完整API见..." |
| 前置于其他 | Tutorial 通常是起点 | 其他文档可假设已完成 Tutorial |
检查清单
完成后验证：
- 新手测试 - 找一个新手，能独立完成吗？
- 时间测试 - 30分钟内能完成吗？
- 成就测试 - 完成后有成就感吗？
- 连贯测试 - 步骤之间过渡自然吗？
- 容错测试 - 出错时有引导吗？
常见错误
| 错误 | 问题 | 改进 |
|---|---|---|
| 信息过载 | 一次教太多 | 拆分成多个教程 |
| 假设太多 | "显然..."、"众所周知..." | 明确说明每个步骤 |
| 缺少反馈 | 不知道是否成功 | 加入成功标志 |
| 太过复杂 | 新手无法完成 | 简化到最小可行 |
| 选择太多 | "你可以A也可以B" | 给出最佳实践 |
| 语言生硬 | 命令式、威胁式 | 改为鼓励引导 |
最佳实践
开篇吸引
- 展示最终效果图
- 说明实用价值
- 设定合理预期
过程设计
- 快速获得首个成功
- 错误恢复指导
- 庆祝每个里程碑
收尾激励
- 总结成就
- 提供证书/徽章（如适用）
- 明确下一步方向
文件命名
按照文件命名规范：
getting-started-[技术].md- 入门教程[技术]-tutorial.md- 基础教程quickstart-[功能].md- 快速开始first-[项目].md- 第一个项目
参考资源
- Diátaxis - Tutorials - Diátaxis 框架对 Tutorial 的定义
- 文件命名规范 - 文档文件命名标准
- How-to 撰写标准 - 任务导向文档规范
记住：Tutorial 不是在"教授一切"，而是在"建立信心和基础"。