文档的灵魂：教导，而非告知

导言

优秀的文档不是信息的堆砌，而是思维的引导。

你是否曾因为阅读一份技术文档而豁然开朗，仿佛作者预见了你的所有困惑？或者，你是否曾面对一个开源库，README 却只冷冷地写着“阅读源码”？技术文档的质量，直接决定了开发者体验的好坏。

今天，我们深入解读 Steve Losh 的经典文章《Teach, Don‘t Tell》，为你揭示编写优秀技术文档的核心哲学与实战方法。

文档的根本目的：是“教导”，而非“告知”

技术文档的终极目标是什么？Steve 给出了一个精炼的定义：带领一个从未见过你项目的人，教导他们成为其专家用户，并在他们成为专家后支持他们。

关键在于“教导”二字。就像教人开车、弹吉他或编程一样，文档的本质是教学。它需要模拟一位耐心的老师，设身处地，一步步引导学生从零到精通。

遗憾的是，许多项目用以下方式敷衍了事，它们都是“教学”的反面教材：

“阅读源码”：好比让学车的人直接拆解汽车引擎。源码对专家宝贵，但对新手犹如天书。
“阅读测试”：如同让学员观看碰撞测试来学驾驶。测试多关注边缘情况，而非日常使用场景。
“文学化编程输出”：就像通过参观吉他工厂来学弹琴。了解制造过程不等于掌握使用技能。
“仅依赖文档字符串”：仿佛副驾上的教练只在被问到特定零件时才开口。缺乏系统引导，用户必须自己猜对“魔法词”。
“使用维基”：堪比一门由多位代课老师轮流上、还允许路人随意插嘴的驾驶课。极易导致内容混乱、过时且缺乏连贯性。

这些并非全无价值，但它们必须在系统的教学文档建立之后，才能作为补充材料发挥效用。在此之前，它们只是逃避编写真正文档的借口。

优秀技术文档的四重奏

一份能真正“教导”用户的完整文档，通常由四个有机部分组成：

1. 初次接触：第一印象决定去留

这是用户邂逅你项目的第一站。它必须清晰回答三个根本问题：

这是什么？ 用平实的语言解释项目是做什么的。
我为什么要关心？ 阐明它的价值：是节省时间、提升稳定性，还是纯粹有趣？更高阶的做法是主动说明项目的权衡与适用场景。
值得我投入吗？ 提供许可证、源码仓库、问题追踪器链接等关键元信息，让用户能快速评估项目的活跃度和可用性。

目标： 在几分钟内让潜在用户明白项目是否契合其需求，并决定是否深入。

2. 黑色三角形：最快的“啊哈！”时刻

名称源于图形编程中“让一个三角形显示在屏幕上”的初始成就。这部分是一个极简的快速上手指南，核心是“Just get something on the screen”。

带领用户完成安装、配置，并运行一个最简单的示例。就像吉他老师第一节课先教三个和弦弹首歌一样，目的是让用户立即获得正反馈，亲身体验项目的“手感”，点燃继续学习的兴趣。

3. 毛线团：系统的教学核心

这是将新手塑造成专家的主战场。它是一个结构化的教程或指南体系，像“毛线团”一样纵横交错，而非线性罗列。

设身处地： 作者需化身教师，想象学生脑中的知识空白，设计一系列循序渐进的“概念台阶”。
精心组织： 内容应按逻辑主题而非单纯的 API 命名空间来划分。提供清晰的目录，帮助用户构建心智模型。
宁可啰嗦： 在简洁的基础上，倾向于稍多解释一点。程序员善于跳过已知内容，但缺失关键连接点会让人彻底迷失。

核心方法： 参考《如何解题》中的教导心法——理解学生已知什么，想让他们学会什么，然后找到一个能将他们向前推进一小步的微小想法，轻轻推动他们。

4. 参考手册：专家的后盾

当用户已成为熟练使用者，这部分便是他们高效的查阅工具。包含：

详尽的 API 文档（强烈建议手动编写，自动生成的价值有限且缺乏“人味”）。
完整的版本变更日志。
项目内部实现细节。
贡献指南。

注意： API 文档与代码中的“文档字符串”目的不同。前者适合深度阅读和关联浏览，后者则针对编码时 REPL 环境的快速查询。

成为好“老师”的两个修炼

练习教学： 最好的准备就是亲自去教。哪怕是非编程的爱好，花时间教给朋友。面对面教学能让你敏锐察觉学习者的困惑，学会预见那些“你以为显而易见”的知识缺口。
投资工具： 一把好键盘（不贵，却能提升写作乐趣）和快速打字的能力（让你不畏惧删改重写），是文档作者的最佳伙伴。

结语：让文档成为桥梁，而非壁垒

Steve 用一则温暖的比喻收尾：好的文档，如同父母在空停车场耐心教孩子开车，从基础操作到复杂路况，逐步引导，及时答疑。最终，孩子不仅能独立驾驶，还能在遇到故障时查阅手册自行修理，甚至理解车辆设计背后的安全考量。

技术文档不仅是项目的说明书，更是社区的门户和传承的载体。“教导，而非告知”——这不仅是一个写作原则，更是一种对使用者同理心的体现。

行动起来： 审视你当前项目的文档，它是在“告知”一堆特性，还是在“教导”一个未来的专家？从补充一个真正的“黑色三角形”快速上手教程开始，让你的项目变得友好而富有吸引力吧。