敏捷开发之设计文档

对于设计文档的一点体会就是，明确需求、精简语言、图文并绘、代码相辅、易于沟通。

下文援引：http://blog.csdn.net/zzhdi/article/details/50929828

在产品研发过程中经常需要编写很多文档，例如：需求文档、设计文档、API文档、验收文档等等。团队成员要花费很多精力去维护众多的文档，甚至有“兄弟，我替你写代码，你替我写文档”的无奈。

敏捷开发宣言
* 个体和互动 胜于 流程和工具
* 可以工作的软件 胜于 详尽的文档
* 客户合作 胜于 合同谈判
* 响应变化 胜于 遵循计划

敏捷宣言的第二条“可工作的软件胜于详尽的文档”，很多人理解为敏捷开发不重视文档，甚至以此为借口逃避写文档。同样，在对待”敏捷开发是否需要架构设计”的问题上也有类似极端的看法。

敏捷宣言在写什么样的文档以及如何写方面并没有给出任何刚性的指导原则，那么在敏捷管理的项目中我们该如何编写文档呢？

首先，我们需要理解敏捷宣言背后的思想。
敏捷4条宣言都是在强调“价值”、“快速交付价值”、“为客户提供价值”的理念。换句话说，研发团队要把精力放在能够为客户带来价值的地方，避免在不产生价值或者ROI（投入回报率）低的任务上浪费时间。

其次，我们要理解文档的作用是什么？文档是用来准确传递信息，帮助理解事物，沉淀知识。

基于以上理解，在遇到是否要写文档的疑问时，可以通过回答两个问题来判断

• 是否有比写文档更高效传递信息的方式？
• 简陋的文档是否满足需要？

从文档的读者来划分

• 读者是项目组外人员
  这类文档往往是需要编写的而且不能“简写”的。例如：用户手册、验收文档、API文档等。

• 读者是项目组内人员
  这类文档能省则省，能简则简。如果能够在每天站会上沟通的，就可以不写。建议高层的系统架构图、内部API文档可以简写。
  如果项目Leader通过类似EasyPM这样管理工具能够查询到的信息，可以在周报中简写甚至省略。

对于可以“简写”的文档，可以考虑使用Markdown格式。

Markdown是一种简单易用的标记语言，用户可以使用这些标记符号以最小的输入代价生成极富表现力的文档。

EasyPM 的文档编辑器使用Markdown语法，并且实时保存/预览、支持代码高亮、文档评论以及全文搜索。在版本管理上，支持手动和自动进行版本管理。文档评论也支持＠功能，可以高效地对文档进行评审。