软件文档写作06-文档表达2

14.5选择表达方法编制软件文档时，应该根据不同文档的性质、类型以及涉众的类型、专业能力等，在确定文档编制计划、内容和步骤后，还要确定文档编制的表达方法。需要编入文档的资料以怎样的方式表达，对该文档涉众以及软件产品、文档等的传播有很大的影响。以软件产品的用户手册为例，其表达方式有以下多种：1.直叙式2.菜谱式3.编号指教式4.剧本式5.四步法任何一本软件用户手册都可能使用这些方法的其中一种或几种。2用户手册编制时常用表达方式介绍：1.直叙式。按照文档中上下文关系，平铺直叙需要编入文档的内容。这是多数文档常用的表达形式。下图是一个直叙式编档的例：订购员填写订购输入单(单据编号P0123)，这张单据有预先印好的订购号。事务输入日期、供货公司名、货号、数量和价格。事务员将此单据信息输入到计算机中，并更新订购文件。注意这种方式会使某些信息在段落中丢失。可以把它和下一种表达方式的例子加以比较32.菜谱方式。菜谱方式，顾名思义，就是写成菜肴或点心的烹制法的样子：搅拌直至均匀，并出现泡沫为止焙烤(350°)一小时语句的第一个词是动词。菜谱方式可以比直叙方式使用更少的字词表达数学内容。将前面直叙方式表达的内容用菜谱方式再表达一次。同样的内容，字数少了，但实际上说的是同一件事。阅读行越短，意味着阅读和理解越快。填写订购输入单，P0123输入日期、供货公司名、货号、数量和价格将单据数据录入计算机更新订购文件提示：每当要给出指示性内容时，使用菜谱表达方式。把动词放在最前面。如果某指示有一个条件，则先说明条件，接着就用一个动词。3.编号指教式。以菜谱式为基础，将文档中描述的软件工作步骤或处理过程加以编号，其表达结果会比直叙式更适合阅读理解。订购员填好订购输入单(P0123)。1.订购号：已印在单据上2.日期：输入当前日期。采用yyyymmdd的8位表达，如将2005年12月2日表示为200512023.供货企业：输入接受订货的企业名。最多25个汉字4.货号：输入要订购的货号。在库存清单中找货号。若为新增，则见新增货物部分5.数量：输入订购数量。最多999996.单价：输入每种货物的价格。最贵￥99999.99(系统将计算本次订购的总金额)7.制表人：制表人签名8.计算机操作员把填写完毕的订购单送计算机录入9.系统管理员将录入后数据处理，并更新订购文件这种表达方式使需要完成的工作十分明确，且数据的长度、格式也有规定，尽管占用的空间稍大，但阅读方便，能使读者快速找到需要的内容。4.剧本式。以菜谱式为基础，将文档以剧本方式表达。也有“演员”，以及动作。下图是这种方法的例：订购员：1.完成订购输入单(P0123)a.订购号：预先印在单据上的顺序号b.日期：输入当前日期。采用yyyymmdd的8位表达，如将2005年12月1日表示为20051201c.供货企业：输入接受订货的企业名。最多25个汉字d.货号：输入要订购的货号。在库存清单中找货号。若为新增，则见新增货物部分e.数量：输入订购数量。最多99999f.单价：输入每种货物的价格。最贵￥99999.99(系统将计算本次订购的总金额)g.制表人：制表人签名操作员：2.将订购单输入计算机系统员：3.数据录入计算机，并更新订购文件剧本式会比编号指教式占用更多的篇幅。但软件编档的目的并不是为了节省篇幅，而是如何使文档更清晰，更容易阅读理解。直叙法使文档内容泛而无重点，编号指教法则突出执行者即角色的作用欠缺。而剧本法者使角色的任务十分鲜明，不同用户只需阅读相关部分即可。5.四步法。对有些功能较多，结构复杂，操作较为灵活的系统，用户比以上的例子会有更多的自由。对于使用第三方软件包开发的系统就更是如此。此时，剧本法已不再适用。即使有几种用户使用软件包，但无法知道谁需要做什么。并且，系统操作过程也不一定是一步接一步，而是需要用户判断接下去做什么，及何时做。对此种情形，唯有直叙式表达和所谓的四步法适用。因为用户手册需要提供用户何时及为什么执行某项功能的指导。而s四步法将比直叙式能更有效的提供这样的指导：(1)动机或理由。用户需要做什么？为什么要做？(2)效果。当用户操作之后，会发生什么？(3)一般步骤。为实现所要的效果，典型的操作步骤是什么？(4)范例。操作和执行结果的例子。下图是四步法编档的一个例子。Wonder-Calc打印命令利用打印命令，可得到您的表格的纸质拷贝。Wonder-Calc在一页纸上的打印宽度和纸的宽度有关。通过指定上、下边缘及打印长度和宽度，可修改Wonder-Calc边缘的设定。打印表格的一般步骤：1.务必连接好打印机，装好打印纸并打开电源2.按P键3.如果Wonder-Calc预定的边缘可接受[RETURN]键，开始打印表格4.如果希望改变边缘，按M键，可得到边缘修改子命令。屏幕显示Wonder-Calc预先设定的边缘参数。使用[TAB]键，把光标移到要修改的边缘处，输入新的的边缘值，按[RETURN]键5.完成第4步后，仍然处在打印命令状态。按[RETURN]键，开始打印表格例如，当在打印命令状态中按M键时，显示Wonder-Calc的预设边缘值：边缘：左：6上：8宽：72长：60纸长：66根据实际使用的纸的大小和表格大小，可修改边缘值为：边缘：左：12上：3宽：60长：60纸长：666.综合式。在具体编制用户手册时，可以根据手册内容或手册读者的需要，采用不同的编档表达方法。例如，对绪言或概述，通常采用直叙式编写。对于读者对象只有一类的那些文档部分，则使用菜谱式或编号指教式比较合适。而有若干类读者的部分，则可以选择采用剧本式编制。具体在用户手册这类文档的编制过程中，编制者可以根据文档涉众的特点，采用灵活的策略，决定文档的表达方式。4.6国际化软件开发编档在当今的全球经济环境下，使用软件的用户可能说着各种不同的语言、来自不同的国家，有着不同的文化背景，如果我们开发的应用软件能够满足这些用户需要，显而易见是益处多多。所谓国际化软件开发和编档，就是要理解什么是国际化．并设计全球可用的应用软件，编制相符合的国际化软件文档。1.国际化软件开发编档的基本要求由于国际化软件的用户分布在不同的国家/地区，并且使用不同的语言，因此，国际化软件的开发编档就要充分考虑和满足各种用户的功能和区域特性的需要。与面向单一语言的软件相比，国际化软件开发及编档具有以下基本要求:(1)全球可用性是国际化设计的目标全球可用，可以保证国际化设计的软件顺利实施本地化，使软件能够运行在不同的语言环境中。为了保持较高的开发效率，为各种语言版本创建共同的单一二进制、全球可用的内核，是一种快速有效的方法。全球可用性的目标使得各种不同语言的版本具有一致的外观、风格和功能。但全球化开发的软件的文档的编制，则必须按照软件去向，符合当地文字规范、文化习俗和阅读习惯。(2)支持不同编码字符集的能力国际化软件及其文档模板应支持不同语言和字符的输入、显示和输出。对于东亚市场的版本，不但需要支持单字节字符集，还需要正确支持双字节甚至多字节字符集。因此，需要在软件国际化设计时，处理正确的字符集编码。国际化软件编档同样会有类似问题，特别是同一国际化软件的不同语言版本文档采用统一模板编制时。一个较好的解决方案是采用Unicode字符编码标准。(3)支持区域信息格式国际化软件需要支持不同区域的信息格式。如，键盘布局、字符串排序、日期、时间、数字、货币、地址、电话号码、度量单位等与特定区域的语言和文化有关的信息。保证不同语言版本的软件能够正确输入、显示、编辑、打印这些信息。相关文档必须完整表达这一类区域信息。(4)国际化特征贯穿于软件项目的全过程软件国际化特征和需求应该从项目最初的市场调研、可行性研究以及项目计划就开始加以考虑。在随后的项目需求分析、系统设计、编码、测试、质量管理，直到软件发布、维护的全过程，应始终贯彻国际化的理念。尽管国际化软件开发过程的技术文档可以采用所在地文字或事先约定的文字编制，但应为最终完成多语种文档编制做好准备。11(5)提高软件的本地化能力提高软件的本地化能力，可以降低本地化的成本，提高软件的质量、可用性和稳定性。因此，要求软件开发人员从软件开发的最初阶段，就应遵循基本的本地化能力准则来开发软件和编档。将需要本地化的内容、文档，与国际化程序代码和文档分开，单独放在资源文件中。(6)尽早测试国际化软件由于必须通过修改程序代码才能解决本地化能力方面的错误，因此，如果到了软件本地化阶段再来修正这些错误，那将会带来很大的困难，并提高开发成本，推迟本地化过程。为此，可以通过伪本地化测试本地化能力，以尽早发现和修改软件的国际化错误。这项工作可以在编码刚刚完成，甚至在详细设计阶段就开始测试。不仅要测试程序，也要同步测试设计文档。122.国际化软件开发编档的基本准则在进行国际化软件开发和编档的实践中，人们逐步总结出一些通用的准则。遵守这些准则，可以避免国际化项目走弯路甚至失败，可以提高软件质量，降低开发和维护成本。国际化软件开发和编档需要遵循的通用准则如下：◘在国际化软件项目的最初期就融入国际化思想，并且使国际化理念贯串于项目的整个生命周期；◘采用单一源文件和文档模板进行多语言版本的本地化，不针对不同的语言编写多套代码和文档；◘将需要本地化的文字与软件源代码分离，并存储在单独的资源文件中；◘软件代码和文档模板支持处理单字节字符集和多字节字符集文字的输入、输出和显示，并且遵守竖排和折行等规则；◘软件代码和文档模板应该支持Unicode标准，或者可以在Unicode与其他代码页(CodePages)互换；13◘软件代码和文档不要嵌入字体名，也不要假设使用某种字体；◘使用通用的图标和位图，避免不同区域的文化和传统差异，避免在图标和位图中嵌入需要本地化的文字；◘菜单、对话框等界面布局及文档模板，能够处理本地化文字的长度扩展；◘源语言及文档描述的文字要准确精简，使用一致的术语，避免歧义和拼写错误，容易进行本地化翻译；◘保证不同区域的键盘布局都能使用源软件的快捷键及文档的使用的一致方法；◘考虑不同区域的法律对软件的要求；◘如果软件中采用第三方开发的软件或组件，需要检查和确认是否满足国际化的要求；◘保证源语言软件及其中内嵌的电子文档可以在不同的语言文化区域和操作系统上正确运行；◘软件代码及文档模板中避免“硬编码”，不使用基于源语言的数字常量、屏幕位置、文件和路径名；◘软件代码及文档模板中字符串的缓冲区长度要满足本地化字符扩展的需要；◘软件及文档模板能正确支持区域排序和大小写转换。144.7软件本地化工程文档处理软件本地化工程是融合软件工程、翻译技术和桌面出版等专业知识的综合性技术，是软件本地化项目中不可缺少的重要环节。软件本地化项目包含的本地化内容，经过软件本地化工程处理后，可以提高软件本地化工作(翻译、桌面排版、测试、项目管理)的工作效率，并且有助于保持本地化内容的一致性。软件本地化工程的目的：软件本地化工程处理的目的是为软件翻译等人员提供精确的、易于翻译的格式文档，并且对翻译后的文档进行工程后处理，为本地化后的软件编译提供正确的内容。具体来说，软件本地化的目的至少包含下面三个方面：1.通过抽取和重复利用已经翻译的资源文件，提高本地化的效率和一致性；2.校正和调整翻译后的资源文件用户界面的大小和位置，保证编译出正确的本地化软件/文档；3.通过修正软件本地化测试发现和报告的Bug，提高软件本地化的质量。15软件本地化工程及文档处理的内容：软件本地化工程处理的内容与具体本地化项目的要求有关。对于一个完整的软件本地化项目，至少包括软件资源文件和联机帮助文档的本地化工程处理。一般，软件本地化工程及文档处理的内容包括以下多个方面：1.制定本地化项目计划，准备本地化工程的专用工具(Preparing)2.检查本地化工程需要处理的文档(Checking)3.抽取并重复利用软件/文档的本地化资源(Leveraging)4.生成字数统计表(WordCount)5.生成本地化术语表(Glossary)6.配置本地化编译环境(BuildEnvironment)7.校正翻