敏捷的文档
程序员文章站
2022-07-15 15:10:15
...
敏捷的文档
作者 滕振宇 发布于 2009年2月23日 下午8时42分
软件项目中有很多种文档，包括需求文档、设计文档、API文档、缺陷报告、进度报告、移交文档、验收文档等等。
在传统的软件项目开发中，每个团队成员都要花费很多时间和精力去维护文档及填写各种表格和报告。第二条敏捷宣言是"可工作的软件胜于详尽的文档"，据此很多人想当然认为敏捷开发不重视文档。更有甚者，有人为逃避写文档而借口敏捷开发不需要文档，成为所谓的PAP（Pretty Adventuresome Programming）。其实这些人忽略了敏捷开发中有很多实践（比如坐在一起、现场客户、测试驱动开发、客户测试、结对编程、信息化工作间等等)，敏捷借助这些实践进行信息交流，起到了文档在传统软件开发中的作用。本文通过分析项目开发中的文档类型与作用来说明敏捷开发中为什么很多文档是不需要的。
首先，需要明确文档的用途，文档是用来交流信息的。关键是团队中信息分享是否及时准确，而这与文档的多少没有必然的联系。就比如James Shore在博文"文档之谜"（http://jamesshore.com/Blog/The-Documentation-Myth.html）里面指出的，很多人指责敏捷开发的文档不够。其实他们忽略了问题的实质，"丰富的文档并不一定是好事，能及时得到答案才是好的"（Myth: Document is good; Reality: Answer is good）。
专业知识或者信息主要分为两类：
* 可以被整理，文档化的知识，一般只占所有知识的30%。
* 占70%的存在于人脑中的隐含(Tacit)知识，只能通过人与人之间的交流来分享，口口相传。因此促进团队内部以及团队之间的交流对信息的传播更加有效。
软件项目文档通常有三种：
* 项目文档，用于项目组内部信息交流，比如需求文档、设计文档、进度报告等。
* 产品文档，通常是有业务价值的，是客户需要的，比如用户手册或者API文档。
* 移交文档，在项目移交或者项目不同阶段之间移交的成果物。
产品文档是客户需要的，是产品的一部分，有业务价值，绝对不能省略。应该在迭代中为其安排一个文档任务。
从敏捷角度来看，另外两类文档中的很多种是可以简化或者省略的。
在敏捷开发过程中，
* 整个团队坐在一起，移交文档变得多余了。精益思想认为移交（Transportation）是很大的一种浪费（参见Mary Poppendieck，精益思想的原则 http://www.poppendieck.com/papers/LeanThinking.pdf），首先移交文档会花费很大的精力，其次很多信息会在移交过程中丢失，另外每个阶段还总会添加一些新的信息。所有团队成员（PO, Dev, QA, Doc）坐在一起，用白板进行面对面的沟通，既省时又省力，还有效。（参见Alistair Cockburn，敏捷项目中的沟通 http://www.agilemodeling.com/essays/communication.htm）
* Product Owner跟团队坐在一起，随时回答团队成员的需求问题，是活的文档。
* 在Sprint计划会议中，团队选择要完成的用户故事（Sprint Backlog上的小卡片），形成Sprint backlog，这其实就是迭代计划。
* 在发布计划会议中，Product Owner会确定发布内容，形成故事墙，这其实就是较为长期的开发计划。
* Dev 和QA一起设计客户测试（一般用Fit类工具）。重要的用户逻辑被设计成客户测试。这种需求（客户测试）是可以运行的，因此永远不会过时（如果出现问题，持续集成系统立刻就会发出警报）。这比传统意义上的需求文档要有效得多。传统文档有太多的问题，比如很少会有人去测试文档的正确性，很少有人去及时更新文档，很少有人去检查需求覆盖率（其实根本没有办法检查，很多工具想当然的提供一些从需求到实现的追踪，但这岂不又是一种形而上学？）。
* 在开发中微观的具体的逻辑可以设计成TDD（或者BDD，行为驱动开发http://behaviour-driven.org/)）的用例，起到了详细需求文档或者设计文档的作用。
* 开发人员使用结对编程（很多好处，参见"我喜欢结对编程" http://www.nomachetejuggling.com/2009/02/21/i-love-pair-programming/，以及 "结对编程：到底有多重要？"http://xprogramming.com/blog/2009/01/28/pair-programming-how-important-is-it/）。健康的系统架构应该是动态的，不断演进的。因此如果把它用文档固定下来，也会出现过期或者不全面的问题。在设计具体模块的时候，团队利用白板设计大体框架并确定方向，然后通过结对编程来具体实现。通过结对编程，可以很好的在团队中分享和演进系统架构信息。
* 团队在每日站立会议中汇报进度，更新状态以及遇到的问题，所有信息会立刻反映到Sprint Backlog，Burdown chart以及各种图表上，成为信息化工作间的一部分，团队可以据此进行自我调整。
* 每一次迭代之后举行反省会议，团队自我改进，也可以设计各种各样的手画表格（Ron Jeffries在个人网站上给了一些例子，http://www.xprogramming.com/xpmag/BigVisibleCharts.htm）来监控团队自身的问题。因此传统的审查及统计的文档就变得多余了。
* 敏捷中高层次的需求通过愿景(Vision)文档体现，这种文档一般只有一页，变化的可能性不大，很容易维护。
* 高层的系统架构图还是必要的。这种高层次系统架构变化的可能性也是很小的，维护成本也比较低。
* 代码即文档。很多敏捷大师十分注重架构清晰度以及代码的可读性（比如Robert Martin总结的S.O.L.I.D原则，Robert Martin的Clean Code，以及Kent Beck的"实现模式"）。在某种意义上我们写的代码其实就是指导计算机完成任务的式样书。式样书就是为了让别人容易读懂（要不然为什么不用二进制去编写程序，放到机器上就可以运行）。
正如James Shore总结的，获得信息的手段有很多。
最优的手段，代码清楚、单元测试完备、命名规范，因此根本不需要问；
其次，只需要问一下旁边的人，或者打一个电话，就可以立刻得到答案，这也就是为什么敏捷鼓励“坐在一起”和“现场客户”r；
再次，Google一下找到答案，这也不错；
……
很次，可以通过读文档找到答案。可是为了找到答案，需要读的文档越多，效果越差...
作者 滕振宇 发布于 2009年2月23日 下午8时42分
软件项目中有很多种文档，包括需求文档、设计文档、API文档、缺陷报告、进度报告、移交文档、验收文档等等。
在传统的软件项目开发中，每个团队成员都要花费很多时间和精力去维护文档及填写各种表格和报告。第二条敏捷宣言是"可工作的软件胜于详尽的文档"，据此很多人想当然认为敏捷开发不重视文档。更有甚者，有人为逃避写文档而借口敏捷开发不需要文档，成为所谓的PAP（Pretty Adventuresome Programming）。其实这些人忽略了敏捷开发中有很多实践（比如坐在一起、现场客户、测试驱动开发、客户测试、结对编程、信息化工作间等等)，敏捷借助这些实践进行信息交流，起到了文档在传统软件开发中的作用。本文通过分析项目开发中的文档类型与作用来说明敏捷开发中为什么很多文档是不需要的。
首先，需要明确文档的用途，文档是用来交流信息的。关键是团队中信息分享是否及时准确，而这与文档的多少没有必然的联系。就比如James Shore在博文"文档之谜"（http://jamesshore.com/Blog/The-Documentation-Myth.html）里面指出的，很多人指责敏捷开发的文档不够。其实他们忽略了问题的实质，"丰富的文档并不一定是好事，能及时得到答案才是好的"（Myth: Document is good; Reality: Answer is good）。
专业知识或者信息主要分为两类：
* 可以被整理，文档化的知识，一般只占所有知识的30%。
* 占70%的存在于人脑中的隐含(Tacit)知识，只能通过人与人之间的交流来分享，口口相传。因此促进团队内部以及团队之间的交流对信息的传播更加有效。
软件项目文档通常有三种：
* 项目文档，用于项目组内部信息交流，比如需求文档、设计文档、进度报告等。
* 产品文档，通常是有业务价值的，是客户需要的，比如用户手册或者API文档。
* 移交文档，在项目移交或者项目不同阶段之间移交的成果物。
产品文档是客户需要的，是产品的一部分，有业务价值，绝对不能省略。应该在迭代中为其安排一个文档任务。
从敏捷角度来看，另外两类文档中的很多种是可以简化或者省略的。
在敏捷开发过程中，
* 整个团队坐在一起，移交文档变得多余了。精益思想认为移交（Transportation）是很大的一种浪费（参见Mary Poppendieck，精益思想的原则 http://www.poppendieck.com/papers/LeanThinking.pdf），首先移交文档会花费很大的精力，其次很多信息会在移交过程中丢失，另外每个阶段还总会添加一些新的信息。所有团队成员（PO, Dev, QA, Doc）坐在一起，用白板进行面对面的沟通，既省时又省力，还有效。（参见Alistair Cockburn，敏捷项目中的沟通 http://www.agilemodeling.com/essays/communication.htm）
* Product Owner跟团队坐在一起，随时回答团队成员的需求问题，是活的文档。
* 在Sprint计划会议中，团队选择要完成的用户故事（Sprint Backlog上的小卡片），形成Sprint backlog，这其实就是迭代计划。
* 在发布计划会议中，Product Owner会确定发布内容，形成故事墙，这其实就是较为长期的开发计划。
* Dev 和QA一起设计客户测试（一般用Fit类工具）。重要的用户逻辑被设计成客户测试。这种需求（客户测试）是可以运行的，因此永远不会过时（如果出现问题，持续集成系统立刻就会发出警报）。这比传统意义上的需求文档要有效得多。传统文档有太多的问题，比如很少会有人去测试文档的正确性，很少有人去及时更新文档，很少有人去检查需求覆盖率（其实根本没有办法检查，很多工具想当然的提供一些从需求到实现的追踪，但这岂不又是一种形而上学？）。
* 在开发中微观的具体的逻辑可以设计成TDD（或者BDD，行为驱动开发http://behaviour-driven.org/)）的用例，起到了详细需求文档或者设计文档的作用。
* 开发人员使用结对编程（很多好处，参见"我喜欢结对编程" http://www.nomachetejuggling.com/2009/02/21/i-love-pair-programming/，以及 "结对编程：到底有多重要？"http://xprogramming.com/blog/2009/01/28/pair-programming-how-important-is-it/）。健康的系统架构应该是动态的，不断演进的。因此如果把它用文档固定下来，也会出现过期或者不全面的问题。在设计具体模块的时候，团队利用白板设计大体框架并确定方向，然后通过结对编程来具体实现。通过结对编程，可以很好的在团队中分享和演进系统架构信息。
* 团队在每日站立会议中汇报进度，更新状态以及遇到的问题，所有信息会立刻反映到Sprint Backlog，Burdown chart以及各种图表上，成为信息化工作间的一部分，团队可以据此进行自我调整。
* 每一次迭代之后举行反省会议，团队自我改进，也可以设计各种各样的手画表格（Ron Jeffries在个人网站上给了一些例子，http://www.xprogramming.com/xpmag/BigVisibleCharts.htm）来监控团队自身的问题。因此传统的审查及统计的文档就变得多余了。
* 敏捷中高层次的需求通过愿景(Vision)文档体现，这种文档一般只有一页，变化的可能性不大，很容易维护。
* 高层的系统架构图还是必要的。这种高层次系统架构变化的可能性也是很小的，维护成本也比较低。
* 代码即文档。很多敏捷大师十分注重架构清晰度以及代码的可读性（比如Robert Martin总结的S.O.L.I.D原则，Robert Martin的Clean Code，以及Kent Beck的"实现模式"）。在某种意义上我们写的代码其实就是指导计算机完成任务的式样书。式样书就是为了让别人容易读懂（要不然为什么不用二进制去编写程序，放到机器上就可以运行）。
正如James Shore总结的，获得信息的手段有很多。
最优的手段，代码清楚、单元测试完备、命名规范，因此根本不需要问；
其次，只需要问一下旁边的人，或者打一个电话，就可以立刻得到答案，这也就是为什么敏捷鼓励“坐在一起”和“现场客户”r；
再次，Google一下找到答案，这也不错；
……
很次，可以通过读文档找到答案。可是为了找到答案，需要读的文档越多，效果越差...