接手过一个别人留下的系统，想加个查询字段，翻遍项目只找到一份三年前的Word接口文档，里面一半接口已经改了参数，另一半从来没写进去过。前端只能照着代码猜参数，联调一周的事拖成一个月。后端系统开发的烂尾，很少是技术崩的，多数是文档烂的。
文档是怎么烂掉的
几乎没有项目是没写过文档的，烂掉的过程都差不多：赶工期时先口头说好了先跑通，文档以后补；以后补的以后永远不会来；半年后新需求进场，新旧信息对不上，大家只能读代码考古。更糟的是人员流动，写代码的人一走，接口为什么这么设计就成了悬案，动哪里都可能炸出历史遗留问题。
让文档活得久的做法
- 文档跟代码放一起：用接口注解自动生成文档，代码改了文档跟着变，人工维护的两份文件必然失同步；
- 联调以文档为准：前端不猜参数，文档里没有的就找后端补，倒逼维护；
- 变更写记录：每个版本改了哪些接口、动了什么参数，一条更新记录列表比长文档有用；
- 交接必查文档：验收外包项目时，文档完整度写进验收条目。
有个客户吃过亏之后定了个土规矩：每次外包结款留两成，文档验收过了才付。下一家供应商听说这条，报价单里主动加了一行文档维护费，你看，规矩立了，市场自己会回应。
补充一点，文档不用追求漂亮，能查、能懂、能对上代码就是好文档。宁可内容朴素但每次都更新，也别图文并茂但三年没动过，文档的质量，就是一个团队的职业底线。
验收文档的标准
别接受一句都有文档。打开看三样：每个接口有没有写清请求参数、返回结构、错误码；有没有可以直接试的演示环境或示例；数据库表结构说明在不在。三样都齐，才算交了能接手的系统。后端系统开发交付的不只是能跑的代码，是别人接得手的东西。
两条建议：合同附件里明确接口文档和数据库说明是交付物的一部分，缺一扣款；自己团队哪怕只有两个人，也坚持文档随代码自动生成的方式，习惯养成了，项目就死不了在文档上。比格网络交付系统时文档是随代码仓库一起移交的，客户接手后自己都能接着开发，这才算交付完成。
