[软件文档写作.pptVIP

?以系统维护人员为主要读者的文档。这类文档主要指系统维护文档等，读者一般包括计算机专业人员和用户两类。这类文档必须提供系统总体功能及每一个具体功能实现的细节，并保证可读性，必要的话应提供系统流程、数据流程等更为详尽的资料。必须做到通过阅读这类文档可以全面、准确、详细地理解系统的有关情况，同时注意专业性与通俗性并重。 ?以系统使用人员为主要读者的文档。这类文档主要指用户手册、参考手册、操作手册及用于宣传系统情况的文档等，这类文档可称为用户文档。这类文档必须克服用户的畏惧心理，树立用户的信任感，提供容易遵循和理解的说明，必须从用户角度出发，使用较为浅显而准确的语言，做到行文流畅，并注意使用例子。 3.确定文档组织方式 (1)标准与约定 (2)确定表达方式 (3)文档组织方式 ?按重要性排序，先提出最重要的思想或项目。主要用在各种绪论中。 ?按需要顺序，先提出读者可能最常需要的信息。主要用在参考手册等文档中。 ?按难易程度，先从最简单的概念人手，然后到较复杂的概念。主要用于培训手册等。 ?按时间（处理）顺序，从写一件事或第一步开始。步骤说明等可用此法。 ?分析法，把复杂问题分为若干个主要问题并加以解释。 ?专题法，按专题划分内容。 ?按程序顺序，根据程序询问信息的次序组织文档。此法适用在线手册和操作手册。 3.3.2 讲究文风 1.语言简洁 (1)语句要短 不要用长句 不要用套话，每一句都应有其自己的作用。 (2)用词要准 涉及概念、定义之类词语用得要准确； 语句中定语用词同样要准； 尽量用大家都熟悉的词语； 不要过多使用形容词； 对于同一个内容，在文档前后应使用一致的词语。 2.读者观点 所谓读者观点就是指在编写文档过程中时时以读者身份来考虑有关问题。 3.尊重习惯 尊重所写这类文档 的有关习惯，如章节号码编写习惯、图表编号习惯等； 尊重读者群中大多数读者的习惯。不同类型、不同层次的读者都会有自己的阅读习惯。 3.3.3 注重表达 在软件文档的话言表达方面，主要应注意这样几点： 第一，注意尊重有关规范、标准，注意使用有关规范、标准； 第二，建立必要的约定并认真执行这些约定； 第三，合理 使用图表、符号； 第四，用好引例。 1.图表 在引用图表过程中应注意这样几个问题： 图表要与文字叙述相结合，成为有机整体； 图表应有一个语言简洁、含义明确的名字； 对图表进行统一编号，以便于引用； 图表的内容应具有一定的代表性； 必要的话应做好图表注释； 图表的栏目名称应准确无二义性； 图表中所用的符号一定是用户能够理解的（即仅能包括标准和约定的符号，其他符号必须说明）； 图表应尽量放在与有关文字叙述靠近的地方。 2.符号 (1) 文档中所有符号必须是明确定义过的。即符号或来自规范标准，或来自约定，或来自习惯用法，或来自语法规则（如标点）。 (2) 每一种符号在文档中所有处使用的含义必须一致，同一个符号不可在甲处代表一个意思，在乙处却代表另一个意思。 (3) 所有符号的使用必须符合语法和规范（标准），所用符号必须与规范（标准）一 致，不可用近似符号代替。 (4) 标点符号是语法的一个组成部分，文档中每一个语句要符合语法规则，每一个标点也应如此，不应出现因标点使用不合理而影响意思表达的问题。 3. 引例 在使用引例时，以下几点应引起重视： (1) 引例使用要适当，要有重点，多则无法突出重点，少则不易讲明问题。这里提一条基本原则：当读完对问题的叙述后还不能明确解决问题的具体步骤时，应使用引例。 (2) 引例要典型，即所使用的引例必须有代表性，必须为读者提供量的概念，最好能提供量的范围。不要用很普通的引例，这对读者帮助不大。 (3) 引例准确，文档编写者应当清楚这样一点：读者对引例的研究要比对文字叙述的研究认真几倍。一个不够正确或不准确的引例给读者带来的危害是相当大的。这不仅多花读者时间和精力，也严重影响读者对文档的信任。 (4) 引例之间应相互补充。有时一个问题可能需要多个引例，这些引例之间应相互补充，各有侧重。 3.3.4 加强文档编写使用的组织管理 软件文档管理主要可以从两方面讲，一方面是软件文档编写过程管理，一方面是软件文档使用过程管理。 1.软件文档编写过程管理 软件文档编写过程管理主要包括：软件文档编写计划管理、软件文档编写进度管理、 软件文档评审管理、软件文档维护管理等内容。 (1)软件文档编写计划管理 对于一个具体的软件系统，系统负责人员必须根据有关要求确定文档编制计划，并指定专人负责管理。这些计划包括： ?明确编制文档的种类、数量，确定文档编写的详细程度，提出文档的预期读者。 ?明确编制文档的具体内容和要求。 ?明确文档编制负责人、审查负责人、批准负责人