软件文档的价值与敏捷开发-优快云博客

本文链接：https://blog.youkuaiyun.com/cxzhq2002/article/details/4288392

前言：
提起软件工程、ISO体系、CMM、RUP，甚至项目管理，都会给人一种强化控制的感觉：要写一堆文档，要填写一堆的报表，要经常开会评审……。
现在软件工厂、蓝领之类的观点颇有市场，一些专家鼓吹通过过程控制、文档驱动、蓝领开发来进行软件项目开发。
这种思想的基础：文档驱动、装配流水线我个人认为是错误的。先说说文档，装配线的事还得准备一段时间。

文档的价值
文档的价值真有那么大吗？我赞成写文档，但不赞成文档驱动，更反感那些将软件人员当作螺丝钉的“工程”思想。

文档可以简单的分成两类：开发文档和管理文档。

一、开发文档
开发文档的用途我认为主要是三点：沟通、质量控制和维护。

1、沟通
文档代替不了沟通。在沟通这个环节，文档的价值很小。
如果公司人员稳定、项目组内部团结、设计开发能力强、代码编写规范、项目规模不大的情况下，文档的沟通价值远远不及小组内部面对面的沟通，这种时候开发文档可以写的很少，可能最重要的是用例分析文档和原型，通过及时的小组会议和代码评审，代码就可以解决问题，所以微软说“代码即文档”有一定道理。（当然这种思想也和进度压力有关系，有些日本公司如日产公司对质量要求较高，给了很充裕的时间写文档，客户要求写，也算作开发时间，但这种客户是少数。）
如果小组内部大部分人员的开发经验不足，就不要想通过文档来指导开发，文档没有什么用途。
大部分开发文档可以通过工具导出，事后补文档也没有什么不对的，：）。

2、质量控制
开发文档的第二个用途是质量控制。
在阶段性工作完成后要进行评审，往往都是将文档做为成果物提交给客户和公司内部评审人员进行评审，很多时候效果不好，走走过场，对项目的下阶段工作没有意义。
项目成果可以分为两类：业务成果和技术成果。
业务成果的评审主要是客户来进行评估，一般给业务流程图、原型就可以了，公司内部人员如果不是该业务领域的专家就没有必要参加，听不懂客户的业务在那耗着还不如回去干自己的事。
技术成果的评审也要是相关领域技术能力很强的人员参加，最好平时就对技术设计思路和方法有充分的沟通，否则到评审前来理解设计思路是很难的，评审的时候对。
从这也可以看出，项目组的内部和外部沟通是非常关键的，否则最后的评审就是看看文档符不符合排版标准，有没有错别字，质量控制也失去了意义。

3、维护
开发文档用途最大的地方就是维护，但是很难做到新人能根据文档进行维护，文档不能代替沟通，没有人进行业务指导，系统很难维护，升级或者改造更困难，对于企业的业务系统而言，指望谁都可以按照文档进行维护是不可能的。

从上面技术文档的三个用途可以看出，技术人员的业务理解、沟通和技术能力是项目成败的关键，文档的作用没有想象的那么大，如果公司的人力资源出了问题，按照所谓的“工厂流水线”方式进行管理，把开发人员当作工具和螺丝钉，把人力资源当作成本来控制，想通过过程体系和文档标准来控制软件开发进度和质量，注定会失败。

后续（二、管理文档）

=======================

http://www.javaeye.com/topic/5876

============================

在项目开发过程中，多少文档，什么程度的文档算是合适的文档？

而今眼目下，很多敏捷过程都提倡在项目开发过程中，保留合适的文档即可，但是什么是合适的文档，缺乏一个明确的标准，这给人一种事实而非的感觉，在执行过程中，也不好操控，这里，分享一下我的看法：

1. 对于项目团队沟通有意义的文档我们必须保留，比如我们需要对需求建模文档，目的是为了让业务人员，架构师和开发人员对系统实现的范围和具体的业务要求达成共识。当然，你可能会反问：如果项目成员都是业务专家，对业务都已经耳熟能详，那还需要这个文档吗？这里我认为就可以大大简化，比如通过几十字的简单范围界定即可，当然，极端的情况，你也可以不要，因为大家都明确，所以不存在再沟通的必要。另外，对于这类文档要尽可能少，并且一定要维护，保持同步。

2. 需要交付客户的文档，在项目开发过程，客户常常会参与到项目的过程中，比如需求的确认，变更的确认等，这些都需要有正式的文档，并且这些文档交付与客户时，一般都是比较稳定的，很多时候都是在里程碑结束时产生的，并将作为下一个阶段开发的基线。这里文档一旦产生就不能直接修改，如果系统一旦产生变化，就只能增补修订文档。

以上两类文档，我认为是必须的，但是上次去一个公司做培训的时候，他们认为关于公司管理要求的文档，在项目开发过程中也是必须的，这里首先介绍一下这个公司的情况，这个公司有一个类似PMO的机构，对公司项目进行战略层面的管理，然后才是项目组——对项目执行层面的管理，公司PMO机构要求进行Agile开发的尝试，但是无形之中，也对新试点项目的管理有一定的要求——传统的管理就要求项目组必须提供这样或者那样的文档。这里我认为这种做法是不正确的，主要原因有两个： 1，这种采用Agile方法的试点应该是一种全新模式的试点，那么就应该摒弃以前的管理模式，如果强行套上以前的管理模型，其实就相当于给Agile方式套上了紧箍咒，还是不是Agile方法就很难说了 2. 公司管理是配合项目执行，而不是项目执行配合公司管理，我认为公司管理机构很大层面上应该是一个服务机构，所以根据项目的不同，监视其不同的里程碑或关键环节，而不是在一个特定的管理规范下——尤其是战略层面的，去要求不同的项目来适应。另外，就过程改进试点本身来讲，也因该放开手脚，让试点组成员多方尝试，并获得改进经验，如果PMO不是特别放心，建议可以委派一个人参与到整个试点项目中。

=======================

http://www.cnblogs.com/YangGang/archive/2009/02/05/1384345.html

==============================

软件项目中有很多种文档，包括需求文档、设计文档、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的"实现模式"）。在某种意义上我们写的代码其实就是指导计算机完成任务的式样书。式样书就是为了让别人容易读懂（要不然为什么不用二进制去编写程序，放到机器上就可以运行）。