How-to 类型文档撰写标准
定义
How-to 是任务导向的文档，指导读者完成特定任务，回答"怎么做"的问题。
核心特征
| 特征 | 要求 | 对比其他类型 |
|---|---|---|
| 目的 | 解决具体问题 | Reference: 提供查询 Explanation: 建立理解 Tutorial: 教授技能 |
| 阅读方式 | 按需查找，快速执行 | Reference: 跳跃查找 Explanation: 顺序阅读 Tutorial: 跟随练习 |
| 内容组织 | 步骤化、任务化 | Reference: 结构化信息 Explanation: 逻辑叙述 Tutorial: 学习路径 |
| 语言风格 | 简洁指令，直达要点 | Reference: 技术精确 Explanation: 通俗易懂 Tutorial: 友好引导 |
| 前置条件 | 明确列出 | Reference: 假设已了解 Explanation: 假设不了解 Tutorial: 零基础 |
适用场景
应该写 How-to
- 解决特定问题的步骤
- 完成具体任务的方法
- 故障排除指南
- 配置和设置流程
- 常见操作指引
不该写 How-to
- 概念原理解释 → Explanation
- 系统学习路径 → Tutorial
- 详细参数说明 → Reference
- 理论背景介绍 → Explanation
必要元素
| 元素 | 说明 | 必需性 |
|---|---|---|
| 任务目标 | 明确要完成什么 | 必需 |
| 前置条件 | 开始前需要什么 | 必需 |
| 操作步骤 | 具体执行步骤 | 必需 |
| 预期结果 | 完成后的状态 | 必需 |
| 常见问题 | 可能遇到的问题 | 建议 |
| 相关任务 | 链接到相关操作 | 建议 |
结构规范
标准结构
markdown
# 如何 [具体任务]
## 目标
[一句话说明要完成什么]
## 前置条件
- 条件1
- 条件2
## 步骤
### 1. 第一步标题
[具体操作说明]
### 2. 第二步标题
[具体操作说明]
## 验证
[如何确认任务完成]
## 故障排除
[常见问题和解决方法]组织原则
- 目标明确 - 开篇即说明要完成什么
- 条件清晰 - 列出所有前置要求
- 步骤编号 - 使用数字编号，便于跟随
- 结果可验证 - 说明如何确认成功
写作要求
语言规范
| 要求 | 说明 | 示例 |
|---|---|---|
| 使用祈使句 | 直接告诉读者做什么 | ✅ "打开终端" ❌ "你需要打开终端" |
| 动作具体 | 每步只做一件事 | ✅ "点击保存按钮" ❌ "保存并关闭" |
| 避免解释 | 专注于操作，不解释原理 | ✅ "运行 npm install" ❌ "运行 npm install（这会安装依赖）" |
| 结果明确 | 说明每步的预期结果 | ✅ "终端显示 'Done'" ❌ "应该成功" |
步骤编写
- 单一任务 - 每个步骤只完成一个动作
- 顺序执行 - 步骤必须按顺序进行
- 独立完整 - 每步都能独立理解
- 可选标记 - 明确标出可选步骤
代码示例
bash
# 命令示例要完整可执行
npm install package-name
# 包含必要的参数说明
git commit -m "message" # -m 指定提交信息质量标准
必须满足
- [ ] 标题以"如何"开头或明确表达任务
- [ ] 前置条件完整明确
- [ ] 步骤编号且顺序正确
- [ ] 每步都有明确的动作
- [ ] 提供验证方法
- [ ] 语言简洁直接
必须避免
- [ ] 冗长的背景介绍
- [ ] 理论原理解释
- [ ] 模糊的指令
- [ ] 跳跃的步骤
- [ ] 缺少前置条件
- [ ] 没有验证方法
特殊类型
故障排除型
markdown
## 问题：[具体问题描述]
### 症状
- 症状1
- 症状2
### 解决步骤
1. 检查...
2. 尝试...
3. 如果仍有问题...
### 预防措施
- 建议1
- 建议2配置设置型
markdown
## 配置 [功能名称]
### 配置选项
| 选项 | 值 | 说明 |
|------|-----|------|
| option1 | value | 用途 |
### 配置步骤
1. 打开配置文件
2. 修改选项
3. 保存并重启快速操作型
markdown
## 快速 [操作名称]
### 方法一：图形界面
1. 点击...
2. 选择...
### 方法二：命令行
`command --option`与其他类型的关系
| 关系类型 | 说明 | 示例 |
|---|---|---|
| 链接到 Explanation | 需要理解原理时 | "了解原理请参考 [链接]" |
| 链接到 Reference | 需要查询详情时 | "完整参数见 [链接]" |
| 链接到 Tutorial | 需要系统学习时 | "新手教程见 [链接]" |
检查清单
完成后验证：
- 目标测试 - 读者能立即知道要做什么吗？
- 条件测试 - 前置条件都列出了吗？
- 步骤测试 - 按步骤能完成任务吗？
- 验证测试 - 能确认任务完成了吗？
- 简洁测试 - 有多余的解释吗？
常见错误
| 错误 | 问题 | 改进 |
|---|---|---|
| "首先你需要理解..." | 过多解释 | 直接给出步骤 |
| "可能需要..." | 模糊指令 | 明确说需要或不需要 |
| "接下来..." | 步骤不清 | 使用编号步骤 |
| "应该会看到..." | 结果不明 | 准确描述预期结果 |
| 缺少故障排除 | 用户卡住 | 添加常见问题部分 |
文件命名
按照文件命名规范：
how-to-[任务].md- 推荐格式[任务]-guide.md- 可接受（明确是操作指南）troubleshooting-[问题].md- 故障排除configuring-[功能].md- 配置指南
参考资源
- Diátaxis - How-to guides - Diátaxis 框架对 How-to 的定义
- Google Developer Documentation Style Guide - 程序化写作指南
- 文件命名规范 - 文档文件命名标准
记住：How-to 不是在"教学"，而是在"指导完成任务"。