在哪在一个易于访问的并可不断更新的资源库中保存文档对保持文档的可用性非常有帮助。用Word文档或类似的格式会让其变得陈旧或过时。 随着项目的滚动进行,文档应当长期保持更新,保持文档对目标受众的有效性。 何时不像在瀑布式开发所期待的那样,在敏捷开发中没有文档阶段。 因此,当功能以增量的方式开发时,文档的编制也应该是增量的,与产品开发一起演进。 如何编制文档在这一点上我们应该决定:
在项目的每一个阶段如何编制文档呢,现在让我来提供一些建议和最佳实践。 项目启动文档在项目初期阶段,只需要少量的文档,因为真正的工作就是如何开始。 当开始编制技术文档时,定义你选定的两个或者三个高层次的架构图,并定义解决方案中需要实现的高层次组件。 在功能方面,用史诗(Epics)来定义产品需要开发的主要特征就可以了。 因为要用敏捷的方式管理项目,不要求预先设计,所以在这个阶段,定义够用的信息,让团队开始工作就足够了。 项目文档在项目进行阶段,随着产品的增量开发,可能需要编制两种类型的文档: A.恰到好处的需求文档-作为产品待办事项列表(Product Backlog)的输入。 B.要实现的系统和业务逻辑-作为每个迭代的输出。 每一种文档都有它自己的目标受众: 目标受众A: 团队。 目标受众B:干系人和最终的维护团队。 这些文档需要对这两类目标受众的需求给出回应。 功能文档 用户故事是敏捷管理项目中最常用的功能文档。用户故事汇聚了足够的信息,告诉开发人员如何实现这些需求,它是用下面的格式描述的:
在迭代计划之前,用户故事的需求描述必须经过干系人的认可,这意味着现在它们已经为计划的迭代做好了准备,它们应该有可靠的信息来源(需求),开发人员知道要实现什么。这需要对目标受众A提供足够的信息。 当用户故事正在开发中时,团队可能会确定新的验收标准,然会添加到用户故事中。 记住,在敏捷中,用户故事不应该是一小块非常详尽的需求描述,而是希望提供什么功能实现的指导方针,这是产品负责人和团队之间未来合作要实现什么产品的承诺。 当用户故事开发完成并被干系人接收之后,那么就可以认为它是已接收的了。这个时候,用户故事需要从Product Backlog(需要实现的一系列功能需求描述列表)中挪到Product Increment(在迭代及所有之前的迭代中已完成的一系列产品代办列表)。 当用户故事以增量的方式完成时,目标受众B所需要的文档在下图1中显示。 技术文档 在研发阶段,开发人员需要运用一些公认的最佳实践(作为敏捷开发方法的一部分),例如测试驱动开发TDD(Test-Driven Development)和行为驱动开发BDD(Behavior-Driven Development),以及结构良好的代码、非技术人员可读等。这个需要提供描述代码的技术文档。 最新的功能和技术文档 因为代码是最新的业务规则和系统实现的最可靠来源,因此基于代码本身是拥有有效文档的最佳方式。 活文档是实现它的一种方式。 活文档或动态文档是持续编辑和更新的文档。活文档的概念依赖于在代码中集成的文档,该文档是基于验收标准,用领域专用语言(Domain Specific Language)来写的,例如用于Cucumber的Gherkin。通过工具来辅助活文档的持续构建,写在用户故事中的验收标准作为代码的一部分已经实现了,并且以一种可读的格式在更新的、典型的在线地址上输出。 提供活文档机制的一些工具包括:Cucumber,Concordion,FitNesse,SpecFlow, Pickles,以及其他。他们都值得一看。 |