大多数软件教程都存在严重缺陷。
教程经常会忘记提及一些关键细节，导致读者无法复制作者的流程。有时，作者会引入不符合读者期望的隐藏假设。
好消息是，编写出色的软件教程比您想象的要容易。只要遵循一些简单的规则，您就可以在众多平庸的指南中脱颖而出。
规则
- 为初学者写作：教程最常犯的错误是使用专家级术语解释初学者级概念。
- 在标题中承诺明确的结果：教程的标题应该简洁地解释读者按照您的指南可以实现什么。
- 在引言中解释目标：当读者开始学习教程时，他们会尝试尽快回答两个关键问题：我应该关心这项技术吗？如果我关心，这对我来说是正确的教程吗？
- 显示最终结果：尽快展示读者在教程结束时将创建的工作演示或屏幕截图。
- 使代码片段可复制/粘贴：当读者按照您的教程时，他们会想要将您的代码片段复制/粘贴到他们的编辑器或终端中。大量教程在不知不觉中破坏了复制/粘贴功能，使得读者难以跟随他们的示例。
- 使用长版本命令行标志：在教程中始终使用长版本。它们更具描述性，因此可以使您的代码更易于阅读，尤其是对于初学者而言。
- 将用户定义的值与可重用逻辑分开：用户定义值和其余代码之间的区别对您来说可能很明显，但对于刚接触该技术的人来说却不清楚。在源代码示例中，要明确哪些值是解决方案的固有部分、哪些值是任意的。
- 让读者免于无脑任务：如果您尊重读者的时间，他们就会欣赏您的教程。不要强迫读者执行繁琐的交互步骤。
- 让计算机评估条件逻辑：当教程变成“选择你自己的上下文情况”风格时，我总是感到失望，但我必须根据我的操作系统环境条件进行选择：
- 保持代码处于可工作状态：有些作者设计教程的方式与折纸魔术相同。这是一个神秘的扭曲和折叠序列，直到你到达终点，然后：哇，这是一只美丽的天鹅！大结局对于折纸来说可能很有趣，但对于读者来说却很有压力。通过保持示例代码处于工作状态，让读者相信他们正在正确地遵循本文。
- 教一件事：一个好的教程应该解释清楚一件事，并且解释清楚。
- 不要试图让自己看起来漂亮：读者并不关心你的玩具应用程序是否看起来很漂亮。他们想要一个能让新概念显而易见的教程。
- 最小化依赖：通过尽量减少教程所需的依赖项数量，让读者更容易理解你的教程。
- 明确指定文件名：“将这一行添加到你的配置文件中”哪个配置文件？在哪里？ 上下文？
- 使用一致的描述性标题：使用标题来组织您的教程。如果您将 25 个步骤的教程组织成 5 个步骤的教程（其中每个步骤有 4 到 6 个子步骤），那么它会让人感觉更友好。
- 证明你的解决方案有效：如果您的教程教读者如何安装工具或集成多个组件，请展示如何使用结果。
- 完整示例链接
banq注：关键是：编写教程的人需要将注意力集中到上下文边界，而不只是内容，内容可以无限，但是必须有限定上下文使之清晰、条理。