主要观点：大多数软件教程存在缺陷，容易遗忘关键细节或带来隐藏假设，而写好软件教程比想象中容易，可遵循 17 条简单规则。
关键信息：

• 规则部分：包括为初学者写作、在标题中承诺明确结果、在引言中解释目标、展示最终结果、使代码片段可复制粘贴、使用长版本命令行标志、分离用户定义值和可复用逻辑、使用明确示例值、避免读者做无意义任务、保持代码处于工作状态、只教一件事、不追求美观、最小化依赖、明确指定文件名、使用一致描述性标题、演示解决方案有效、链接到完整示例等 17 条规则。

• 各规则详解：

  • 为初学者写作：教程常见错误是用专家术语解释初学者概念，应避免行话等，用读者能理解的语言介绍，如用现代工具创建简单网页介绍 React。
  • 承诺明确结果在标题中：标题应简洁明了地告知读者通过教程能达到的效果，如“如何在 Python 中读取 CSV 文件”比“成为 Python CSV 忍者的完整指南”更清晰。
  • 在引言中解释目标：引言应尽快回答读者的两个关键问题，即是否应关心该技术以及此教程是否适合自己，如介绍 Docker 时应说明其解决的痛点。
  • 展示最终结果：尽快展示读者最终能创建的工作演示或截图，减少对目标的歧义，如展示终端 UI 截图。
  • 使代码片段可复制粘贴：避免教程中代码片段破坏复制粘贴功能，如包含 shell 提示符字符会导致问题，应使用非交互标志、用&&连接命令、只在演示输出时显示 shell 提示符、排除可复制文本中的行号等。
  • 使用长版本命令行标志：命令行工具的长版本标志更具描述性，便于初学者阅读，如在 grep 命令中使用长版本标志。
  • 分离用户定义值和可复用逻辑：在代码示例中区分固有于解决方案的元素和读者可自定义的元素，如使用环境变量或命名常量，使意图更清晰。
  • 使用明确示例值：代码示例中使用变量名和值应避免引起读者误解，选择明确且有意义的示例值，如在 SQLite 示例中使用更清晰的表名和字段值。
  • 避免读者做无意义任务：避免让读者进行繁琐的交互式步骤，如手动编辑文件，应提供可实现相同效果的命令行片段。
  • 保持代码处于工作状态：教程示例代码应保持工作状态，给读者信心，如先展示有错误的代码，再逐步完善。
  • 只教一件事：教程应专注于教一件事，避免将不相关的技术混入，如在 Hugo 博客教程中只专注于客户端搜索。
  • 不追求美观：教程应专注于解释新概念，避免用大量无关的 CSS 代码使示例看起来漂亮，如简化 Vue 教程中的代码。
  • 最小化依赖：减少教程所需的依赖，降低读者的安装配置难度，延长教程的使用寿命，如避免使用大型日期解析库。
  • 明确指定文件名：在教程中明确给出编辑文件的完整路径和行号，如在 Webpack 配置文件中指定优化设置的位置。
  • 使用一致描述性标题：使用标题结构教程，使标题清晰、一致且符合逻辑，如用更有信息量的标题代替简单的标题，检查标题的大小写、观点和动词时态等。
  • 演示解决方案有效：在教程中展示安装工具或集成组件后的使用结果，如访问 nginx 成功页面。
  • 链接到完整示例：链接到包含教程中所有代码的代码仓库，并可展示在持续集成系统中的运行情况，如分分支展示教程的不同阶段。

  重要细节：文中通过多个具体示例详细说明了每个规则的应用和注意事项，如各种代码片段、不同类型教程的对比等，以帮助读者更好地理解和遵循这些规则。