为什么要写文档？
项目初期，团队决定要写文档。理由是"文档很重要，能帮助新人快速上手"。
听起来很有道理，我们就开始写了。README、API 文档、架构文档、开发指南，能写的都写了。
写文档的实际情况
第一个月：热情高涨
第一个月，大家都很积极。每个功能都写文档，每个 API 都写文档。文档写了很多，看起来很全面。
但问题也来了：写文档的时间比写代码的时间还长。一个简单的功能，写代码 1 小时，写文档要 2 小时。
第二个月：开始应付
第二个月，大家开始应付了。为了完成任务，写了很多没意义的文档。比如"这个函数做什么"，但函数名已经说明了。
更糟糕的是，很多文档和代码不一致。代码改了，文档没改。时间长了，文档就过时了。
第三个月：没人看
第三个月，发现没人看文档。新人来了，直接看代码，不看文档。问问题，直接问人，不查文档。
更烦的是，文档写了很多，但找不到。文档分散在各个地方，README、Wiki、代码注释，不知道在哪里。
文档真的有用吗？
我们统计了一下，写了半年文档，真正有用的文档不到 20%。大部分文档都是：
- 重复代码已经说明的内容
- 过时的，和代码不一致
- 找不到的，分散在各个地方
- 没人看的，写了也没用
真正有用的文档，是那些解释"为什么"的。比如为什么这么设计，为什么选这个方案。但这些文档往往很难写，需要深入思考。
什么时候该写文档？
用了一年多，我觉得这些场景该写文档：
- 架构设计：解释系统架构、技术选型、设计决策
- 复杂逻辑：解释复杂的业务逻辑、算法、流程
- API 接口：说明 API 的用法、参数、返回值
- 部署流程：说明如何部署、配置、运维
什么时候不该写文档？
这些场景我觉得不用写文档：
- 简单的代码：代码已经很清楚，不需要文档
- 经常变的功能：文档维护成本太高
- 内部工具：只有内部用，不需要文档
- 原型和实验：还不确定要不要，写文档浪费
我们的策略调整
后来我们调整了策略：
- 不再追求文档全面，只写有用的文档
- 重点写架构设计、复杂逻辑、API 接口
- 代码注释写"为什么"，不写"做什么"
- 文档和代码放在一起，方便维护
这样调整后，文档数量减少了 70%，但质量提升了。真正有用的文档保留下来，没用的文档都删了。
文档工具的选择
我们试过几个文档工具：
- Markdown：简单，但功能有限
- GitBook：功能强大，但配置复杂
- Confluence：企业级，但太重
- Notion：好用，但不够专业
现在主要用 Markdown + GitHub Pages，简单实用。
如果重新开始
如果重新开始一个项目，我会：
- 不追求文档全面，只写有用的文档
- 重点写架构设计、复杂逻辑、API 接口
- 代码注释写"为什么"，不写"做什么"
- 文档和代码放在一起，方便维护
总结
文档不是银弹，不是写得越多越好。关键是要写有用的文档，而不是为了完成任务凑数。
如果你们项目也在写文档，建议先评估一下文档的价值。如果大部分文档都是摆设，不如删掉，把时间花在更有价值的地方。
文档是工具，不是目标。目标是帮助团队协作，如果文档不能达到这个目标，那就换其他方法。