接手过一套没有文档的系统，那种痛苦每个工程师都经历过。一个简单的改动要花半天逆向代码，问了一圈老员工，每个人说的还不一样，最后靠试错才搞明白。也接手过另一套系统，文档清晰、和代码同步，新人一周就能独立干活。
两者的差距只在一样东西，文档。代码会重写、人会流动，唯有文档能把知识沉淀下来传下去。但多数团队对文档的态度是矛盾的，都知道重要，都不愿意写，写了也不维护，最后文档比代码还旧，成了误导而不是帮助。这篇讲怎么打破这个怪圈。
为什么文档总是写不好
图：对症下药——降门槛、写价值、建维护机制
先诊断病因，才能对症下药。
最常见的借口是「没时间」。其实不是没时间，是写文档的即时回报太低。写代码马上能跑起来，有成就感。写文档是给未来的别人看的，对自己当下没好处，所以本能地往后排。这是激励机制的问题，不是时间的问题。
第二个原因是不知道写什么、怎么写。很多人写文档就是把代码逻辑用文字复述一遍，既痛苦又没用，读者看文档还不如直接看代码。这种文档写一次就再也不想写了。
第三个原因是维护的绝望。文档写完就开始过时，代码改了文档没跟着改，三个月后文档和现实脱节，比没有文档更危险。经历过几次「文档骗了我」之后，大家就不信文档了。
认识到这三个根因，解决方向就清楚了。降低写作成本，让写文档不那么痛苦。写真正有价值的内容，不是翻译代码。建立维护机制，让文档不容易烂掉。
写什么，区分文档的类型
图：每类文档服务不同读者，写之前先定位类型
不同类型的文档，读者和目的不同，写法完全不一样。混为一谈是文档写不好的大原因。
入门文档，给新人或第一次接触的人看。目标是让人在十分钟内跑起来、理解这个东西是干嘛的。重点是快速上手路径，别塞原理和细节。新人最怕的就是看了一堆概念还是不知道第一步干啥。
API 文档，给调用方看。目标是让人不看源码就能正确调用。重点是参数说明、返回值、错误码、示例。示例比说明文字有用十倍，一个能跑的例子胜过千言万语。
设计文档，给团队和未来维护者看。目标是讲清楚为什么这么设计、有哪些权衡。重点是背景、约束、方案选择、代价。这层文档最稀缺也最值钱，因为它记录的是决策过程，是代码里看不出来的东西。
运维文档，给 oncall 的人看。目标是出故障时能快速定位和处理。重点是监控指标怎么看、常见故障怎么排查、应急预案是什么。这份文档的价值在凌晨三点出事的时候才体现。
怎么写，站在读者那边
写文档最大的误区是，站在作者视角而不是读者视角写。
作者视角的文档长这样，「这个模块用了工厂模式和策略模式，通过依赖注入组装。」读者看完更糊涂了。读者视角的文档长这样，「你想加一个新的支付渠道，只需要实现这个接口，然后在这里注册。三步搞定。」
区别在于，读者视角回答的是「我想做 X，怎么做」，作者视角回答的是「这个东西内部是怎么构成的」。前者有用，后者往往是自嗨。
几个具体的写法原则。结论先行，每段第一句话就是这段的重点，后面是支撑。读者忙的时候只看每段第一句就能抓住大意。用具体的例子代替抽象描述，「调用 getUser(id) 返回 」比「该接口返回用户信息」清楚一百倍。写读者会问的问题，不写你想说的东西。
能用图就别用一大段文字。流程图、时序图、架构图，一张好图胜过一千字描述。但图要配文字解读，别扔一张图就完事，读者不一定看得懂你图里每个箭头的含义。
文档的维护，比写更难
图：维护机制的核心——让文档和代码在同一个 PR 里一起变
文档腐烂是必然的，除非有人维护。这是文档管理最被低估的难点。
最有效的维护机制是把文档和代码绑在一起。代码改了，对应文档必须在同一个 PR 里改，reviewer 检查。这样文档和代码就不会脱节，因为它们是一起变的。文档放在代码仓库里（比如和模块同目录的 README），而不是放在一个没人看的 wiki 里，能大幅提高维护概率。
给文档标日期和负责人。每份文档写明最后更新时间、由谁维护。过时的文档要有机制识别，比如半年没更新的文档自动标记「可能已过时」，提醒读者谨慎对待、提醒维护者复查。
定期清理。像清代码债一样清文档债，定期把过时的、重复的、没用的文档删掉或更新。文档越多越乱，精简的文档库比臃肿的更有用。
降低写作门槛
让写文档不那么痛苦，人才会愿意写。
模板是个好东西。给每种文档类型提供一个模板，写的人填空就行，不用从零想结构。模板降低的不是质量是门槛，有了框架，往里填内容就容易多了。
别追求完美。第一份文档写得粗糙没关系，先有再优。一份不完美但存在的文档，比一份完美但永远没写的文档有用一万倍。文档可以迭代，写个 v1 先用起来，用的时候发现哪里不清楚再补。
把写文档纳入 Definition of Done。一个功能没文档不算完成，让它成为开发流程的一部分，而不是可选的附加项。流程化了，就不靠意志力去坚持了。
如果团队还没有写文档的习惯，别一上来就要求所有模块都写全套文档，那是劝退。从一个最痛的模块开始，或者从新人 onboarding 文档开始，先让一份好文档发挥价值，让大家尝到甜头。有了正反馈，写文档的习惯才推得动。
文档是团队成熟的标志
一个团队文档写得好不好，能直接反映它的成熟度。
成熟的团队把文档当成代码一样认真对待，因为它知道人员会流动、知识会断层，只有文档能让团队的认知沉淀下来。文档好的团队，新人融入快、故障响应快、协作摩擦少，这些都是实打实的收益。
不成熟的团队永远在「太忙了没空写文档」和「因为没文档所以更忙」之间循环。打破这个循环不需要更多时间，需要的是认识到，写文档不是额外负担，是给自己和团队省时间的投资。今天花一小时写的文档，未来会替你省下十小时的解释和排查。
文档不是写作，是工程。把它当成一件值得用工程思维去对待的事，设计、编写、维护、迭代，它就会成为团队最值钱的资产之一。
