系统开发的文档管理

ftonny

因为目前参与一个系统的开发管理工作，希望多了解一些有关的知识。现在遇到的一个最大的问题就是开发文档的管理，好像每个程序员都不是很愿意做文档，应此在版本控制方面就存在问题，不知道各位有什么好的建议？

jinzhi

最初由 ftonny 发布\r\n[B]因为目前参与一个系统的开发管理工作，希望多了解一些有关的知识。现在遇到的一个最大的问题就是开发文档的管理，好像每个程序员都不是很愿意做文档，应此在版本控制方面就存在问题，不知道各位有什么好的建议？ [/B]

\r\n\r\n文档和程序编制应该分开，程序人员应该按照文档要求来编制程序，而不应有其自主决定该如何开发，我觉得国内许多小项目的开发都是在程序员有一个基本的了解后就开始开发程序，然后在开发过程中不断改进，因此导致文档的建立存在问题。你作为管理人员我认为应该先确定系统分析人员，并要求系统分析人员提供完整的文档，在文档完成后再要求程序人员进行编制。不过实现起来比较困难，大家觉得是不是这样？

ftonny

我明白是要把文档和编程分开，而且应该在编程之前做好文档，按文档要求Coding，但是如果在Coding的过程中有变化，是要用什么好办法去控制文档和实际程序的Match，或者说是版本的统一呢？谢谢。

jinzhi

最初由 ftonny 发布\r\n[B]我明白是要把文档和编程分开，而且应该在编程之前做好文档，按文档要求Coding，但是如果在Coding的过程中有变化，是要用什么好办法去控制文档和实际程序的Match，或者说是版本的统一呢？谢谢。 [/B]

\r\n这时说明一个问题，你的系统分析做得不够深入，或者没有得到用户的最后确认，当然这种问题肯定会存在，我觉得这时你应该制定一个流程，而不是要求程序员去修改分析文档，用户或者编程人员认为需要更改设计的，必须通过系统分析员，由系统分析员下达最后的确认修改设计，并提供相应的文档，否则编程人员无权更改设计。

ftonny

楼上说得有道理，总之就是无论任何变动，都需要先取得系统分析员的同意，在文档中作出记录之后才可以修改程序，是不是这个意思呢？

cg2001

本来文档和开发的人不一定要相同，应该各司其职。\r\n你用过Rational的SODA这个软件吗？可以看一下。\r\n\r\n不过中国的程序员不愿意写东西倒是真的，例如代码说明等

ftonny

谢谢楼上，其实我想说的就是这个问题，我们的程序员都是绝顶聪明的，可是现在却比不上印度，少的就是管理，我听说他们在读大学的时候，如果被淘汰，不是一个人，而是一个学习小组，好像很残酷......//thinking

cg2001

中国人缺少的是团队精神和诚信。\r\n也许是中国人太聪明了，而不喜欢规范。就像有种说法：“中国人一个人是条龙，一群人是条虫”；足球也罢，程序员也罢，都是如此。

ftonny

好了，不扯远了，言归正传，我找了几篇有关文档管理的文章，供大家参考。\r\n\r\n（一）\r\n文档的管理和维护 \r\n\r\n　　在整个软件生存期中，各种文档作为半成品或是最终成品， 会不断地生成、修改或补充。为了最终得到高质量的产品，达到上 节提出的质量要求，必须加强对文档的管理。以下几个方面是应注意做到的： \r\n\r\n\r\n　　①软件开发小组应设一位文档保管人员，负责集中保管本 项目已有文档的两套主文本。两套文本内容完全一致。其中的一套可按一定手续，办理借阅。 \r\n\r\n\r\n　　②软件开发小组的成员可根据工作需要在自己手中保存一些个人文档。这些一般都应是主文本的复制件，并注意和主文本保持一致，在作必要的修改时，也应先修改主文本。 \r\n\r\n\r\n　　③开发人员个人只保存着主文本中与他工作相关的部分文档。 \r\n\r\n\r\n　　④在新文档取代了旧文档时，管理人员应及时注销旧文档。 在文档内容有更动时，管理人员应随时修订主文本，使其及时反映更新了的内容。 \r\n\r\n\r\n　　⑤项目开发结束时，文档管理人员应收回开发人员的个人文档。发现个人文档与主文本有差别时，应立即着手解决。这常常是未及时修订主文本造成的。 \r\n\r\n\r\n　　⑥在软件开发过程中，可能发现需要修改已完成的文档，特别是规模较大的项目，主文本的修改必须特别谨慎。修改以前要充分估计修改可能带来的影响，并且要按照：提议、评议、审核、批准和实施等步骤加以严格的控制。\r\n\r\n(To be continued)

ftonny

（二）\r\n\r\n如何编写高质量“软件需求说明书”（上）\r\n\r\n原著：Karl E Wieger，Process Impact \r\n\r\n　　你的工程应该有个好的起点。一个小组要带领客户进入需求启发阶段而且你要写软件需求说明书。这份说明有些大，但客户会很重视，所以说明必须得到赞同。\r\n\r\n\r\n　　现在你正在设计其中的一个特性，已经发现了需求的一些问题。你可以用多种不同的方式解释需求15；需求9 的说明正好与需求21相反，你因该相信哪一个？需求24非常含糊，你根本不明白它的意思；你不得不花上一个小时与2位开发人员讨论需求30，只因为你们对其各有各的理解；并且，唯一能够澄清这些问题的客户没有给你们答复。你被迫破解众多需求的含义，并且你能预料到，如果你错了，你要做大量的重复工作。 \r\n\r\n\r\n　　许多软件需求说明书（SRS）写得非常糟糕。任何产品的质量需要其原始材料的质量保证，糟糕的软件需求说明书不可能产出优秀的软件。不幸的是，几乎没有开发人员受过与需求的抽象、分析、文档、质检有关的教育。而且，没有非常多的好需求可以借鉴学习，部分原因是很少有工程可以找到一个好的借鉴，其他原因是公司不愿意将其产品说明书放在公共区域。\r\n\r\n\r\n　　这篇文章描述了高质量需求叙述和说明的几个特性（特点）。我们将用这些观点检查一些有缺陷的需求，带着痛楚重新编写。而且我会谈一些如何编写好的需求的提示。你也许想通过这些质量标准评估你的工程需求。对于修订，也许迟了，但你会学到一些有用的东西，并帮助你的小组在下次编写出更好的需求。\r\n\r\n\r\n　　不要期望能够编写出一份能体现需求应具备的所有特性的SRS。无论你怎么细化、分析、评论和优化需求，都不可能达到完美。但是，如果你牢记这些特性，你就会编写出更好的需求，生产出更好的产品。\r\n\r\n高质量需求叙述的特性\r\n\r\n　　我们如何从一些有问题的需求中分辨出好的软件需求？这一节将分别介绍需求叙述应体现的6个特性，下一节将从整体上介绍SRS文档应具备的特性。判断每个需求是否具备应有的特性的一种方式是由持有不同观点的工程资金管理人所作的正规检查。另一种有力的方法是在编写代码前依据需求编写测试例子。测试例子能够明确显现在需求中描述的产品行为（特性），能够显现缺陷、冗余和含糊之处。 \r\n\r\n\r\n　　正确：每个需求必须精确描述要交付的功能。正确性依据于需求的来源，如真实的客户或高级别的系统需求说明书。一个软件需求与其对应的系统需求说明书相抵触是不正确的（当然，系统需求说明书本身可能不正确）。\r\n\r\n\r\n　　只有用户的代表能够决定用户需求的正确性，这就是为什么在检查需求时，要包括他们或他们的代理的关键所在。不包括用户的需求检查就会导致开发人员的：“这是没意义的”，“这可能是他们的意思”等众所周知的猜测。 \r\n\r\n\r\n　　可行性：在已知的能力、有限的系统及其环境中每个需求必须是可实现的。为了避免需求的不可行性，在需求分析阶段应该有一个开发人员参与，在抽象阶段应该有市场人员参与。这个开发人员应能检查在技术上什么能做什么不能做，哪些需要需要额外的付出或者和其他的权衡。\r\n\r\n\r\n　　必要性：每个需求应载明什么是客户确实需要的，什么要顺应于外部的需求，接口或标准。每个需求源于你认可、具有权说明需求的原始资料，这是考虑必需的另外情形（译注，此句翻译不顺，请参照原文：Another way to think of “necessary” is that each requirement originated from a source you recognize as having the authority to specify requirements）。跟踪每个需求回溯到出处，如用例，系统需求，规章，或来自其他用户的意见。如果你不能标识出处，可能需求只是个镀金的例子，没有真正的必须。\r\n\r\n\r\n　　优先权：为了表明在一个详细的产品版本中应包含哪些要点，需要为每个需求，特征，或用例分配实现的优先权。客户或其代理都应有强烈的责任建立优先权。如果所有的需求都被视为同等重要，那么由于在开发中，预算削减，计划超时或组员的离开导致新的需求时， 项目经理将不能起到作用。优先权的作用是提供给客户的价值，实现的相关费用，实现相关联的有关技术风险。 \r\n\r\n\r\n　　我是用3种级别的优先权：高优先权表明需求必须体现在下一个产品版本中，中优先权表明需求是必须的，但是如果需要可以推迟到晚一些的产品版本中，低优先权表明有它很好，但我们必须认识到如果没有充足的时间或资源，它可以被放弃掉。\r\n\r\n\r\n　　明确：需求叙述的读者应只能从其得到唯一的解释说明，同样，一个需求的多个读者也应达成共识。自然语言极易导致含糊。要避免使用一些对于SRS作者很清楚但对于读者不清楚的主观词汇，如：用户友好性，容易，简单，快速，有效，几个，艺术级，改善的，最大，最小等等。每写一个需要都应简洁，简单，直观的采用用户熟知的语言，不要采用计算机术语。检查需求模糊的有效方式包括需求说明书的正规检查，根据需求写测试，建立用户的假想来说明产品某个特定部分预期的特性。 \r\n\r\n\r\n　　可证实：看你是否能够做出测试计划或其他验证方式，如检查和实证，来决定在产品中每个需求是否正确的实现。如果需求是不可验证的，决定需求是不是正确的实现就成了判断的事。需求之间不一致，不可行，不明确也能导致不可证实。任何需求如果说产品将要支持什么也是不可证实的。\r\n\r\n高质量需求说明的特征\r\n\r\n　　一个完整的SRS不仅是包括长长的功能性需求列表，还包括外部接口描述和一些诸如质量属性，期望性能的非功能性需求。下面描述了高质量的SRS的一些特性。\r\n\r\n\r\n　　完整：不应该遗漏要求和必需的信息。完整性也是一个需求应具备的。发现缺少的信息很难，因为根本不存在。在SRS中将需求以分层目录方式组织，将帮助评审人员理解功能性描述的结构，使他们很容易指出遗失的东西。\r\n\r\n\r\n　　在需求抽象时，相对于系统功能，你过多的注意用户的业务，将导致在需求的全局观和引进不是真正必需的需求上显得不足。在需求抽象上，应用用例方法会发挥很好的作用。能够从不同角度察看需求的图形分析模型也可以检查出不完整性。\r\n\r\n\r\n　　如果你知道已缺少一些信息，使用TBD（to be determined）标准标志可以突出这些缺陷，当你在构建产品的相关部分时，就可以从一个给定的需求集中解决所有的缺陷。\r\n\r\n\r\n　　一致性：一致性需求就是不要于其他的软件需求或高级别的系统（商业）需求发生冲突。需求中的不一致必须在开发开始前得到解决。只有经过调研才能确定哪些是正确的。修改需求时一定要谨慎，如果只审定修改的部分，没有审定于修改相关的部分，就可能导致不一致性。\r\n\r\n\r\n　　可修改性：当每个需求的要求修改了或维护其历史更改时，你必须能够审定SRS。也就是说每个需求必须相对于其他需求有其单独的标示和分开的说明，便于清晰的查阅。通过良好的组织可以使需求易于修改，如：将相关的需求分组，建立目录表，索引，以及前后参考（照）。\r\n\r\n\r\n　　可追踪：你应能将一个软件与其原始材料相对应，如高级系统需求，用例，用户的提议等。也能够将软件需求与设计元素，源代码，用于构造实现和验证需求的测试相对应。可追踪的需求应该具有独立标示，细密和结构化的编写，不应过大，不应是叙述性的文字和公告式的列表。\r\n\r\n(to be continued)