封闭式开发小记(6)：封闭式开发的文档管理

在封闭式开发中，我们要尽量把花在写文档上的时间减到小，这样才能保证更多的时间用于实现业务需求上。只能尽可能短的时间做出可以演示的需求，才能让客户满意。但是虽然没有原来需求说明和详细设计那么多。但是基本的用于落实需求和用于交流的文档还是要的。其实个人认为最好的文档就是代码了，关于代码既是文档可以参考《clean code》,下面着重介绍一些不可再省的文档了：

用户故事（user story）：

定义：以人为中心用业务语言简要描述客户需求。对最终用户来说最有意义的一个功能。

主要包括以下三个部份：卡片（用卡片来记录）：对话（用客户的语言，关注客户关注的问题）：验证：（记录一些用可以检查这个用户故事是否通过）

格式：作为…我需要…以便…

范例：做为一个产品经理,我需要查询产品列表,然后,以便给最紧密的联系人打电话.

范例分析：目标用户是产品经理，他希望按一定的条件查询产品列表，并且把查询的数据集进排序，对关键字权重高的要排到前面。并且显示的联系人信息不要求太全，但最重要的就是他的电话。且望Ary card间用于实现业务需求上。

不同的人对应同样功能可能有不同的要求，如仓库操作人员想通过使用查询产品列表完成仓库的拣选商品的操作，以提升仓库工作人员的工作效率。其中受众是仓库操作人员，业务操作是使用手机进行商品的拣选，目的是提升仓库操作人员的效率，实现商业目标。

用户接收测试（uat）：这个用户故事如何演示，才能让客户明白，这个功能是实现的。

接上面的这个查询的例子：用户在文本框中输入对应的关键词，多个关键词是以空格或逗号隔开。点击查询按扭后，页面上显示所有相关产品列表，其中和关键字最相关的产品显示在最前面，且每个产品后面都对应显示出联系人的电话号码。

参与人员：测试人员、产品经理、真实用户、交互功能设计人员

用例(use case)：

定义：由特性分解而来的一个可以用来做功能测试的小情节。

每个用例可以转化为一个单元测试。在每次重构后可以用来验证。

格式：

用例名应该是一个用主动语态动词短语来表示的用例目标>

使用语境：<目标较长的描述，如果需要，还包括触发事件>

范围：<设计范围，在设计时将系统作为一个黑盒来考虑>

级别：<概要、用户目标、子功能三者之一>

主执行者：<主执行这的角色名称或主执行者的描述>

项目相关人员和利益：<用例中项目相关人员和关键利益的列表>

前置条件：<我们所希望的，周围环境已经达到的状态>

最小保证：<在所有退出操作前，如何保证得到必须的信息>

成功保证：<目标完成时环境的状态>

触发事件：<什么引发了用例，可能是时间事件>

主成功场景：

<在这里写出从触发事件到目标完成以及清楚的步骤>

<步骤编号#><动作描述>

扩展：

<在这里写出扩展，每次写一个扩展，每一个扩展都指向主场景中的特定步骤>

<被改变步骤><条件>：<动作或子用例>

技术和数据变化列表：

<在这里写出场景中因技术或数据变化而引起的可能分支>

<步骤或变化编号#><变化列表>

相关信息

<项目所需要的所有附加信息>

注：除了使用相关的文档外，其它建模方式可以是UML，可以是Word文档，也可以是白板上的图。只要让参与各方都能确认，并且能记录下来就行了。看自的习惯了，在前一篇可以看到，我们基本上都用时序图的方式，这样比较好理解。

范例：

请参考《编写有效用例》P110页

《UML团队开发实用手册》

参与人员：产品经理、开发人员、测试人员（可无）

代码签入时备注(check in note)：当出现两个开发人员同时编写一个源代码文件时，清楚的注释能够快速定位一些因交叉签入和测试不彻底造成的bug。有一次，和我配队开发的同事他有事请假一天，然后我发现他有一个项目文件是签出的状态，然后我撤销签出后，把新的源码签入后填写了备注。第二天他来的时候，由于看到获取最新版本的时候发现了这个备注，然后合并修改了。最后特别果注明多个版本同时更新时的同步信息，尽量保证版本号、bug号等的完整。特别要注意和任务号的对应，这样能按bug查找版本号，再查到对应的业务需求（任务）。

日报\周报(daily report\weekly report )：

以周报为例：今天的任务是什么，今天完成的任务（未完成的可以加上百分比），明天的任务。

代码复查报告(code review report)

按小组分开，按编码规范一条条过。注意要把多余的文件给删掉。

PS：代码既是文档。但是代码终究还是语言，是语言就可能多种口音和方言，虽然都是属于汉语。不排除口吃的人除外呢。特别，实现还不是那么清楚的时候，我们只能通过文档，把实现尽量放到后面，这样才能防止较多的反复和争吵。本文还少了一个最为关键的部份，就是工作量的估算和记录，这是一个团队成长最重要的环节。由于可以独立成篇，这里不再赘述。