tech-tutorial

技术教程

优秀的技术教程只有一个目标：让读者从不知道如何完成某件事，变为能够完成它。 这需要可运行的代码、具体步骤，以及如实说明可能出错的地方。 本技能将指导你规划大纲、撰写并验证符合这一标准的教程。

适用场景

• 为库、CLI 工具或 API 编写入门指南
• 创建读者可以在终端逐步跟随操作的教程
• 通过实践练习讲解技术概念
• 编写补充 API 参考文档的操作指南

不适用场景

• 生成 API 参考文档（使用 scribe:doc-generator）
• 润色现有文案（使用 scribe:slop-detector）
• 编写不包含可运行步骤的高层架构概览
• 编写不含实践内容的概念性文章

方法

步骤 1：确定范围和受众

动笔之前，先回答以下问题：

• 这是写给谁的？明确读者层级：newcomer、practitioner、 expert，或用一句话描述读者画像。教程默认面向 newcomer；如果不是，请说明具体假设
• 有多少读者？每位读者会阅读几次？
• 到教程结束时，读者将构建或完成什么？
• 读者读完后必须记住的一句话是什么？ （这是核心论点，不是主题）
• 读者必须安装的唯一先决条件是什么？
• 哪些内容明确不在范围内？

在草稿中将这些答案写成一个标题区块。 如果无法用一句话回答“读者将完成什么”，说明范围太广。如果无法 用一句话说明核心论点，说明教程还没准备好开始撰写。

受众规模和阅读频率决定了读者时间预算 （参见 scribe:slop-detector 模块 document-economy.md）。 一篇有 500 位开发者各读一次的教程，会消耗 40 小时的 读者时间预算。请据此投入写作时间。

读者层级决定草稿可以包含哪些内容。如果请求没有指定读者， 请先询问，不要猜测：scribe:slop-detector 模块 audience-targeting.md 包含层级表和苏格拉底式提问集。

面向 newcomer 的教程要从头到尾只保留一条可行路径。 替代方案、内部机制，以及显而易见的方法为何会失败，都属于 expert 内容。将它们放入 docs/deep-dive/<topic>.md，并在 引言中用一句话链接到该文档，说明深入讲解面向哪些读者。不要为了符合 读者层级而删掉这些内容。暂停下来比较三种方法的教程， 已经无法继续带领读者从不会做到会做。

步骤 2：规划大纲

加载：@modules/outline-structure.md

开始撰写正文之前，先生成逐节大纲。 每个章节条目都必须用一句话说明读者将在该章节中做什么或学到什么。 章节标准顺序和各章节类型的目标长度请参阅大纲模块。

步骤 3：先起草代码示例

加载：@modules/code-examples.md

先写代码，再写正文。 教程中的每个代码片段都必须先在真实环境中运行。 只为不明显的代码行添加注释。 格式和错误处理规则请参阅代码示例模块。

步骤 4：围绕代码撰写正文

正文的作用是解释代码的功能及其原因。 遵循以下规则：

• 每个步骤写一个段落：说明运行什么、代码做什么，以及预期结果
• 每个命令块后注明预期输出
• 全文统一使用第二人称“你”
• 不要叙述读者接下来要做什么，直接呈现下一步

步骤 5：逐步增加复杂度

加载：@modules/progressive-complexity.md

从最简可运行示例开始。 只有在基础示例正常运行后，才引入变体和边界情况。 分层规则和节奏建议请参阅渐进复杂度模块。

步骤 6：检查冗余表达

完成初稿后，运行：

Skill(scribe:slop-detector)

继续之前，修复所有第 1 级问题。 请特别注意：

• 第 1 级词汇冗余（参见 scribe:slop-detector 词表）
• 三段式形容词堆叠（“快速、高效且可靠”）
• 句末堆叠分词短语（以“，从而实现……”结尾的句子）

步骤 7：质量门槛

根据以下清单检查已完成的教程：

内容：

• 所有代码块都经过测试，并能产生所述输出
• 相关时，先决条件部分列出确切版本
• 每个步骤都说明预期结果
• 故障排除部分涵盖至少两种常见故障模式

句子层面：

• 没有第 1 级冗余词汇
• 每 1000 个词中，破折号少于 2 个
• 项目符号占比低于 40%
• 每行长度控制在 80 个字符以内

文档层面（文档精简模块）：

• 第 1 步中的主旨出现在引言段落中
• 结尾处重申主旨（理想情况下，教程中段也重申）
• 没有重新罗列刚刚完成内容的“总结”部分
• 没有章节以重述其标题开头

受众层面（受众定位模块）：

• 第 1 步中声明受众层级；若未明确，则询问
• 每个章节都服务于该层级
• 将超出受众层级的细节提取到链接的深入探讨中，而非删除

必需的进度项

1. tech-tutorial:scope-defined - 已注明受众、目标和范围之外的内容
2. tech-tutorial:outline-approved - 已确认章节大纲
3. tech-tutorial:code-tested - 已在真实环境中验证所有代码片段
4. tech-tutorial:prose-drafted - 已撰写操作指南正文
5. tech-tutorial:slop-scanned - 冗余表达检测已通过
6. tech-tutorial:quality-verified - 质量门槛清单已通过
7. tech-tutorial:user-approved - 已获得最终批准

模块参考

• 章节顺序和篇幅目标参见 modules/outline-structure.md
• 代码片段格式和注释规则参见 modules/code-examples.md
• 节奏和分层指导参见 modules/progressive-complexity.md

与其他技能集成

技能	使用时机
scribe:slop-detector	撰写初稿后、批准前
scribe:doc-generator	编写配套 API 参考章节时
scribe:style-learner	模仿现有教程的语气时

完成标准

• 开始撰写前已确认教程大纲
• 撰写前已声明受众层级，而非事后声明
• 所有代码片段都已在真实环境中测试
• 冗余表达得分低于 1.5（清晰）
• 超出受众层级的内容已移至链接的深入探讨中，而非 留在读者的阅读路径中或被删除
• 质量门槛清单已通过
• 已获得用户批准