软件文再档写作08-文档写作2.pptVIP

* 5.7 软件文档的质量要求 一个好的文档资料能起到多种有益的作用。如，有助于系统顺利开发，有助于管理人员监督和管理软件开发，有助于用户了解软件的功能和正确操作流程，有助于维护人员进行有效的维护。 而一个质量差的软件文档，不仅使读者难以理解，给使用者造成许多不便，增加软件成本，甚至可能造成更加有害的后果。 因此，软件编档必须保证其质量。 造成软件文档质量不高的原因多种多样，但主要可以归纳为两条： 1. 缺乏实践经验，缺乏评价文档质量的标准； 2. 不重视文档工作，或是对编档工作安排不恰当。 最常见的就是，软件开发时不重视编档，最后却搞突击。 高质量的软件文档应当具备以下几方面的特点： 1. 针对性 编档前即能根据涉众对象，按不同文档类型、不同涉众层次、不同分发策略，确定编档目的、目标、标准、方案、计划和资源。 2. 精确性 文档行文应十分确切、一致，没有多义、重复、矛盾等现象。 3. 清晰性 文档力求简洁，表述清晰，如有可能，则配以适当图表，以增强可阅读性。 4. 完整性 任何文档都是完整的、独立的，是自成体系的。 5. 灵活性 前已多有述及，不再赘述。 6. 可追溯性 软件开发各阶段编制的文档与各自对应阶段完成的工作有紧密联系，相邻阶段的文档也会有一定的继承关系，因此，必要时相关文档能做到跟踪追查。 5.8 软件文档编制技巧 拥有规范准确的软件文档，是每个软件产品保证质量所必须的必要条件，同时对软件企业自身非常有利，也能够让用户从中受益。而软件产品的正确使用，也依赖于文档的准确可靠。 那么，如何才能编制出好的文档呢？下面是一些建议： 1. 从技术角度进行文档的编制和评价 由于软件文档是作为软件产品的技术资料的特点，因此编制时应从技术角度着手，以忠实于技术事实为准绳，保证编制步骤、描述内容和使用图表资料的准确性。 2. 明确编档人员的责任 文档质量欠佳的主要原因之一就是责任不明确，没有承认编档人员的劳动付出。因此，明确责任，明确编档者的工作贡献，是提高文档质量的有效途径。 3. 让编档人员对开发项目有充分准确的认识 由于软件开发人员工作强度大、时间紧，所以不少企业大型项目的编档工作就交由专职的编档人员完成。但编档人员对编档对象了解的程度，尤其是了解的充分性和准确性，将直接影响到编档的准确性。 所以，为了让专职编档人员能够编制出高质量的产品文档，应该从以下几个方面为他们提供条件： (1) 将编档人员组合进开发小组 (2) 让编档人员多参加有关产品设计与开发的工作会议 (3) 让编档人员参与到技术要求、功能规划及设计方案的开发工作中去 (4) 鼓励编档人员更多的了解有关产品及其相关的技术背景 4. 组织开发人员参与文档评审 软件开发人员对产品方案、技术、结构的掌握，对编档工作有十分重要的意义，如何使得这些信息能被编档人员所了解和把握，对软件文档的质量至关重要。 一个有效方法是，让开发人员参与到文档评审工作中去，增加开发人员对文档的了解，增加开发人员与编档人员的沟通交流，使编档人员能及时从开发人员那里获取所需信息，以保证编档工作的顺利进行，保证编档质量。 5.9 软件编档的2个实例 尽管软件编档存在着很多灵活性，但是，具体在实施编档任务时，为了达到编档质量的目标，还是需要控制这种灵活性。 对于具体的软件开发项目，需编制文档的种类、详细程度等，应取决于开发组织的管理能力，以及项目自身的规模、复杂性和风险等因素。而制订一个可操作的编档实施规定，用以规范在什么情况下应该编制哪些文档、文档的质量目标等，是开发组织应该首先完成的工作。 由于国内目前在这方面还缺乏成熟的经验，因此仅提供2个根据国外经验制订的2个例子，以供参考。 当然，这2个例子也未必一定能与国内现状吻合，大家在参考时还应与各自面临的实际情况协调，才能获取有益的结果。 1. 用求和法确定应编制的文档 该方法的要点是提出12个考虑因素来衡量一个应用软件，以及每个因素可能取值的范围。任务负责人可用这12个因素对所要开发的程序进行衡量，以确定每个因素的具体值。然后，把这12个因素的值相加，得到一个总和，就可以根据这个总和的值，来确定应该编制的文档的种类。 具体例题： 随着杭州逐步具备国际会展中心的基本功能，各类国际国内、专业民用展览，各种演出活动以及各种形式的会议、培训等活动将会越来越多，参与活动的人士也会有各种各样，有的需要购买入场券，有的需要安排住宿，有的需要安排会议活动(如大会发言、小型研讨、专题讲座、新闻发布等，及场所)，有的需要安排游览，也有的需要安排翻译、领