源代码是最佳文档,没错,但不是全部真相,另外,其可阅读难说最佳!
文档最重要的的作用是沟通,显然文档不是好的沟通工具。文档对自己可用作思考与规划的工具,对团队成员是相互沟通的工具,对组织内部其他团队是知识传递的工具,对组织是资产(某种意义上是需要投入成本维护的负债!),对客户是投资回报的结果之一,对社会是责任/法律核查的依据。
写文档要考虑的要素:
谁是读者?因何而写?
读者要的是什么?
如何让读者易读易理解?
何时写最好?涌现式文档。
如何产出、存放及交付?
敏捷文档的价值观是增值且恰好(Just Enough)。
敏捷文档的准则:轻量化;高质量(准确、最新、简洁、易读、严谨);尽可能趋向自动化(方便、易于维护、保证质量);同步化(明确描述的文档与程序同步,即活文件 living document)。
敏捷开发的文档一般包括:
需求文档:What 及 Why。
架构文档:How 软件系统如何架构运行;
程序文档:精化需求/产品代码 + 验收条件/测试代码;技术实现上表现为实例化需求SBE/验收测试驱动ATDD/行为驱动开发BDD等。