需求文档编写讲训.ppt

我们目前对待文档写作的态度：内心上抵触、应付了事。 反观老外在这方面的认真态度，我们不但需要文档化，还需要将文档化做好。 开发人员写文档常犯的低级错误： 1.不使用标准模板； 2.文档各部分内容不全，关键词、摘要、缩略语、文档标题、页眉页脚中错误非常多，让人没有再看下去的心情； 3.文档标题、字体格式混乱，层次不清； 4.编写建议在文档完成后仍然保留。 关于格式，应尽可能使用模板自带的格式，如：标题1～4、正文首行缩进、表格文本、代码、图号等。 主动语气、被动语气： “本模块提供××功能”； “××功能被本模块提供”。 该练习突出基本要求中的几点： 1.句子和段落要短； 2.避免歧义； 3.应追求图文并茂的效果。 只是简单地进行了分段，阅读起来更有层次感更清晰。同时修正了“约”、“左右”等模糊的描述。 图形表述方式理解更容易，上图已将房间布局信息很清晰表达出来，缺的是尺寸信息，可以在图中标注或附以文字说明，则能完全表达清楚。 图形应具有“自明性”，即只看图，大体上就可理解图意。但不应为追求自明性而使图形过于杂乱，必要时应佐以少量的文字说明。 写作工程文档不同于文学创作，务必要严谨，避免使用白话。 用词要简洁. 避免使用人称称谓。 避免使用“这”、“那”；避免使用白话。 一致性、清晰性。 需求设计合一模板 ＝ 需求模板 ＋ 移植设计模板。 对于规模在几百行的特性，建议使用需求设计合一的模板，但可以根据需要，参照独立的需求模板、设计模板增加一部分章节。 对于规模上千行的特性，建议大家还是使用独立的需求模板和设计模板写作。 后面内容主要针对独立的需求模板和移植设计模板进行讲解，设计模板仅简单介绍。 完整性：一是功能点不能少，所有的分配需求(AR)都必需实现；二是每个功能点内的描述必须完整，专用的术语、缩略语要进行解释，输入、处理、输出不能有遗漏，可以结合SLOC项目举例说明。 清晰性：需求叙述的读者应只能从其得到唯一的解释说明，同样，一个需求的多个读者也应达成共识。反例：“代码行统计性能很高”。 一致性：不能与AR矛盾；前后的多项需求或者一项需求不能出现前后矛盾的说法。反例：AR要求统计物理代码行，需求却统计了逻辑代码行；AR与SRS针对注释行的定义不一致等等。 可行性：每一项需求都必须是在已知系统和环境的限制范围内可以实现的。举例：下水道井盖为什么要做出圆形，而不做成正方形、长方形、椭圆形或六边形等 可验证性：每一项需求是否能够通过设计测试用例或其它方法来确定产品是否确实按照需求实现了。举例：上述不清晰的需求一般也不可验证。 除上述不足之外，该需求点还存在如下问题： 1.标题中不应再包含“Functional Requirements1 功能需求1”的描述 2.…… 关于“流畅”－以周杰伦唱歌为例，其fans肯定认为很流畅，其他不少人则不会这么认为。 这里的图形只是给出一个概要性描述的示例，并不表示概要性描述必须采用这种方式或者此为标准的表达图形。 同样，这里的图形也仅仅是一个示例而已。 项目假设是我们先说严格意义的和非严格意义的：严格意义是在当前时间点根据当前拥有的各种工具无法确定的事物或事件，而且这些事件会对你的项目造成影响。你的项目是在假设条件成立的情况下进行了。由于假设是不确定因素，所有项目的所有假设都是项目的风险，只是风险的严重程度不同而已，对于关键的风险应该转化为项目的风险，在后续进行风险的分析和跟踪。比如项目现状是没有测试人员，你可以假设项目在进入测试阶段的时候，能够招聘到两名技能符合要求的测试人员。同时可以将该条假设转化为风险，即可能存在无法招聘到测试人员，而影响测试和整体进度的风险。 另外还想说的是非严格意思的假设，比如我们经常和别人讨论问题时候爱说假设你的说法是正确的，这个应该说是一种非严格意思的假设，因为在当时这个点究竟他的说法是否正确是可以通过其它评估方法或工具进行判断的，是一个确认的事情，而不是远期未确认的一个预测性的事情。 在项目开始时候，我们可能并没有一套很体系化的评估和测评工具能够来测评我们每个项目成员的技能是否达到要求，所以可以做个假设，假设项目中的每个成员都达到了组织或项目要求的技能要求。也可以做为假设。 约束，是指所有对你项目有制约性的内部或外部因素都可以做为约束。约束有技术方面的约束如系统的开发必须采用分布式技术，约束也可能是非技术性的，如项目的资源或成本方面的约束。约束应该是一个在项目过程中不会发生变化的客观因素，另外约束也可以转化为风险进行跟踪，如项目可能存在某项约束不能满足的风险。 项目的依赖和承诺都分为项目内部的项目外部的。依赖和承诺密切不可分。下游工序依赖于上游工序的产出物，而上游工序需要做出承诺在哪个时间点给下游工序交出工件。项目内部的依赖可以体现到进度计划的甘特图上面，