一个人开发要不要写文档，我改了做法
我上一个项目给接口写了完整的说明文档，四十多条，配了请求示例和字段表格。项目上线三个月后我回去改一个接口，打开自己写的文档，发现它跟代码已经对不上了——有两个字段是后来加的，改动的时候谁也没想起去更新那份文档。从那次起，我一个人开发要不要写文档这件事，我的答案变了。
先把真实结论放这儿：文档要写，但不是写给人看的说明书，是写给未来的自己看的决策记录。判断标准很简单——这份内容，我从代码里能不能读出来？
二、我踩过的账：四十多条接口文档的结局
那份文档的问题不在写得不好，在它的正确性完全靠自觉维护。
代码改了，编译器会提醒我哪里不对；测试挂了，CI 会报红。但文档过期了，没有任何机制会告诉我。它只会安静地变成一份错误的资料，等到某天有人照着它做，才反过来坑人。
四十多条接口说明，我现在的做法是全部删掉，改成让工具从代码注释里生成。生成的东西不一定好看，但它不会撒谎。
三、现在我留的四类文件
第一类是项目启动说明。从零到跑起来要几步、需要哪些外部依赖、哪个命令启动。换台电脑的时候这份文件救过我，这一点在换台电脑就跑不起来，环境怎么统一里写得更细。
第二类是关键决策记录。每次我放弃一个方案、选了另一个，就写一小段：当时面对什么情况、为什么没选另一条路。这类内容代码里读不出来，是最值得留的。
第三类是待办与已知问题。已知但暂时不修的 bug、绕过去的边界情况，写清楚在哪、为什么绕。不然下次遇到同样的报错，我会重新排查一遍。
第四类是对外接口的字段约束。哪些字段可空、取值范围是什么、超时怎么处理。这部分我用注释写在代码里，让工具生成，不单独维护一份。
四、我删掉的三类文档
第一类是全量接口手册。理由上面说过，它会过期。
第二类是架构设计文档里那些漂亮的组件图。我画过几张，画完之后代码该往哪写还是往哪写。真正有用的是「模块之间只能通过哪个入口调用」这种一句话约束，而不是图。
第三类是进度汇报式的文档。一个人开发，进度我自己知道。
这四留三删之后，文档的量少了，但每次打开都有用。这也是我后来清理工具时用的同一套判断：留着的东西必须能被用到，工具是这样，文档也是这样。
五、换个人能不能复制
能，但有个前提：你得接受文档是不完整的。
我早期总想把文档写全，写全的代价是维护成本高到根本维护不动。现在我只记录那些从代码里读不出来的部分。这个标准客观上让文档变少了，但也让它活了下来。
唯一的例外是接口注释。这部分不要偷懒，它跟代码在同一个文件里，改动时顺手就能跟上，是性价比最高的一种文档。
常见问题
Q：一个人开发要不要写文档，最少要写什么？
A：至少写项目启动说明和关键决策记录。前者让你换机器能恢复，后者让你记得当初为什么这么设计。
Q：文档总是过期怎么办？
A：把能从代码生成的部分交给工具生成，只人工维护代码里读不出来的内容。人工维护的部分越少，过期的概率越低。
Q：接口文档要不要单独维护一份？
A：不建议。字段约束写在代码注释里，用工具生成，改动时和代码一起提交，比单独维护一份手册可靠。
相关阅读
本文作者西米，37 岁程序员，一个人加五个 AI 员工在跑一家公司。踩过的坑和真实账本都写在公众号「西米分享」。
完整代码、踩坑清单与最新进展，都在公众号。
📱 关注公众号「西米分享」