《软件文档写作08文档写作2.ppt》由会员分享，可在线阅读，更多相关《软件文档写作08文档写作2.ppt（13页珍藏版）》请在三一办公上搜索。
1、1,5.7 软件文档的质量要求 一个好的文档资料能起到多种有益的作用。如，有助于系统顺利开发，有助于管理人员监督和管理软件开发，有助于用户了解软件的功能和正确操作流程，有助于维护人员进行有效的维护。而一个质量差的软件文档，不仅使读者难以理解，给使用者造成许多不便，增加软件成本，甚至可能造成更加有害的后果。因此，软件编档必须保证其质量。造成软件文档质量不高的原因多种多样，但主要可以归纳为两条：1.缺乏实践经验，缺乏评价文档质量的标准；2.不重视文档工作，或是对编档工作安排不恰当。最常见的就是，软件开发时不重视编档，最后却搞突击。,2,高质量的软件文档应当具备以下几方面的特点：1.针对性 编档前即
2、能根据涉众对象，按不同文档类型、不同涉众层次、不同分发策略，确定编档目的、目标、标准、方案、计划和资源。2.精确性 文档行文应十分确切、一致，没有多义、重复、矛盾等现象。3.清晰性 文档力求简洁，表述清晰，如有可能，则配以适当图表，以增强可阅读性。4.完整性 任何文档都是完整的、独立的，是自成体系的。5.灵活性 前已多有述及，不再赘述。6.可追溯性 软件开发各阶段编制的文档与各自对应阶段完成的工作有紧密联系，相邻阶段的文档也会有一定的继承关系，因此，必要时相关文档能做到跟踪追查。,3,5.8 软件文档编制技巧 拥有规范准确的软件文档，是每个软件产品保证质量所必须的必要条件，同时对软件企业自身非
3、常有利，也能够让用户从中受益。而软件产品的正确使用，也依赖于文档的准确可靠。那么，如何才能编制出好的文档呢？下面是一些建议：1.从技术角度进行文档的编制和评价 由于软件文档是作为软件产品的技术资料的特点，因此编制时应从技术角度着手，以忠实于技术事实为准绳，保证编制步骤、描述内容和使用图表资料的准确性。2.明确编档人员的责任 文档质量欠佳的主要原因之一就是责任不明确，没有承认编档人员的劳动付出。因此，明确责任，明确编档者的工作贡献，是提高文档质量的有效途径。,4,3.让编档人员对开发项目有充分准确的认识 由于软件开发人员工作强度大、时间紧，所以不少企业大型项目的编档工作就交由专职的编档人员完成。
4、但编档人员对编档对象了解的程度，尤其是了解的充分性和准确性，将直接影响到编档的准确性。所以，为了让专职编档人员能够编制出高质量的产品文档，应该从以下几个方面为他们提供条件：(1)将编档人员组合进开发小组(2)让编档人员多参加有关产品设计与开发的工作会议(3)让编档人员参与到技术要求、功能规划及设计方案的开发工作中去(4)鼓励编档人员更多的了解有关产品及其相关的技术背景4.组织开发人员参与文档评审 软件开发人员对产品方案、技术、结构的掌握，对编档工作有十分重要的意义，如何使得这些信息能被编档人员所了解和把握，对软件文档的质量至关重要。一个有效方法是，让开发人员参与到文档评审工作中去，增加开发人员
5、对文档的了解，增加开发人员与编档人员的沟通交流，使编档人员能及时从开发人员那里获取所需信息，以保证编档工作的顺利进行，保证编档质量。,5,5.9 软件编档的2个实例 尽管软件编档存在着很多灵活性，但是，具体在实施编档任务时，为了达到编档质量的目标，还是需要控制这种灵活性。对于具体的软件开发项目，需编制文档的种类、详细程度等，应取决于开发组织的管理能力，以及项目自身的规模、复杂性和风险等因素。而制订一个可操作的编档实施规定，用以规范在什么情况下应该编制哪些文档、文档的质量目标等，是开发组织应该首先完成的工作。由于国内目前在这方面还缺乏成熟的经验，因此仅提供2个根据国外经验制订的2个例子，以供参考
6、。当然，这2个例子也未必一定能与国内现状吻合，大家在参考时还应与各自面临的实际情况协调，才能获取有益的结果。,6,1.用求和法确定应编制的文档 该方法的要点是提出12个考虑因素来衡量一个应用软件，以及每个因素可能取值的范围。任务负责人可用这12个因素对所要开发的程序进行衡量，以确定每个因素的具体值。然后，把这12个因素的值相加，得到一个总和，就可以根据这个总和的值，来确定应该编制的文档的种类。具体例题：随着杭州逐步具备国际会展中心的基本功能，各类国际国内、专业民用展览，各种演出活动以及各种形式的会议、培训等活动将会越来越多，参与活动的人士也会有各种各样，有的需要购买入场券，有的需要安排住宿，有
7、的需要安排会议活动(如大会发言、小型研讨、专题讲座、新闻发布等，及场所)，有的需要安排游览，也有的需要安排翻译、领导接见或其它会务服务。对于部分会展、演出活动还需要在筹办期间拟订邀请宾客名单，发出邀请信，并对回执进行管理。购票、邀请宾客及被邀宾客回执均可以在分布式环境中完成，会议期间的活动安排可以在网上实时发布，甚至部分会议活动被安排在网上实时直播。根据以上叙述，规划设计一个简单的会务管理系统，完成上述功能的管理需求。求和法的具体表格在4.5节已给出，后面再列：,7,8,使用求和法的具体过程是：1.按前表中的12个因素衡量所要开发的程序，得到每个因素的值。在该问题中，我们通过分析可以得知各个因
8、素的得分如下：(1)创新程度 1(7)开发投资(人月)1(2)通用程度 3(8)重要程度 1(3)应用范围 2(9)完成程序修改的平均时间 3(4)应用环境的变化 1(10)数据I/O平均时间 5(5)设备复杂性 3(11)编程语言 1(6)参加开发人数 1(12)并行软件开发 22.把衡量所得的各个因素的值相加，得总和之值。在本例中，这个值 24,9,3.根据总和之值，从下表中，查出应编制的文档种类。,文档的种类,因素值总和,表中：*，表示此文档应编制，但不必太正规；*，表示应根据所开发软件的实际需要来确定是否需要编制此文档。,现在，可以依据表格，获知本例需要编制的文档种类，总共有9种之多。
9、,10,2.根据软件规模大小确定应编制的文档 为了避免在软件开发过程中文档编制的不足或过分，也为了避免前一种方法中对某些因素的把握出现误判，一个简便的方法是，把对软件文档的编制要求同软件的规模联系起来。这就是本例的出发点。这里，我们把软件的规模分为四级：(1)小规模软件，源码行数小于5000；(2)中规模软件，源码行数约1000050000；(3)大规模软件，源码行数约100000500000；(4)超大规模软件，源码行数大于500000。对此，相应规模软件应该编制的文档种类，参见下表：,11,对于源码行数在500010000、50000100000的软件，其文档编制的种类介于两级之间，可由项
10、目负责人根据项目的具体情况，参照上表规定确定。,12,在本例中，我们再次使用上一个例子的问题，来尝试确定其应该编制的文档种类。具体例题：随着杭州逐步具备国际会展中心的基本功能，各类国际国内、专业民用展览，各种演出活动以及各种形式的会议、培训等活动将会越来越多，参与活动的人士也会有各种各样，有的需要购买入场券，有的需要安排住宿，有的需要安排会议活动(如大会发言、小型研讨、专题讲座、新闻发布等，及场所)，有的需要安排游览，也有的需要安排翻译、领导接见或其它会务服务。对于部分会展、演出活动还需要在筹办期间拟订邀请宾客名单，发出邀请信，并对回执进行管理。购票、邀请宾客及被邀宾客回执均可以在分布式环境中
11、完成，会议期间的活动安排可以在网上实时发布，甚至部分会议活动被安排在网上实时直播。根据以上叙述，规划设计一个简单的会务管理系统，完成上述功能的管理需求。,13,根据基于LOC的软件规模估算方法，我们可以按国际、国内、专业展览，会议、培训，凭票、免表，与会参展人士接待，会场布置，网络环境，网上信息发布等多个功能模块得到关于本例规模的LOC估算表，得出其规模大约是2500031000左右的估算结果。这样，就获知系统规模为“中”，其所需编制的文档种类根据上表即可获知。在实际的项目实际活动中，软件规模的确定，既可以按照LOC方法估算，当然也可以按照FP方法确定。具体按照何种方法确定，既与项目类型、性质有密切关系，也与项目采用何种开发技术、开发工具、开发环境等有密切关系。,
