8.3.2.8 插图设计者
插图设计者主要职责包括:
———运用高水平的图形技能和图形工具进行图形开发;
———凭借常规图形设计工具的背景知识,培养熟练使用指定的图形开发工具的技能;
———与平面设计师沟通图形开发标准;
———与编写者沟通图形内容。
16
GB/T16680—2015/ISO/IEC26511:2011
8.3.2.9 校订者
校订者的职责包括:
———根据文档计划检查和修订用户文档初稿,改善文本和插图的布局、清晰性、简洁性、完整性和可
用性;
———检查文档初稿是否符合使用的国际标准、国家标准或组织内部标准;
———检查和纠正文档编写风格上的错误和不一致性,运用高水平的书面语言表达能力改善文档。
注:可以在各个级别进行修订,从初稿的重构和重组到信息或语法错误。修订的水平宜与用户文档的重要性一致。
8.3.2.10 质量专家
质量专家的职责是:
———制定文档开发过程,供文档开发团队成员使用;
———评估文档是否符合相关规定;
———审查文档开发过程,确保其符合内部和外部标准。
8.3.2.11 索引编制者
索引编制者的职责包括:
———编制索引(包括纸质版和电子版索引),运用经验和技术选择索引关键字和内容;
———使用索引生成工具制作索引,必要时加深对工具的了解。
8.3.2.12 测试人员
测试人员的职责包括:
———评估文档中信息的准确性;
———评估文档的可用性;
———在文档可用性和精确性方面,提供适当的修改意见。
注:用户文档测试人员可以提供一些文档和软件的修改建议。
8.3.2.13 翻译或本地化工作协调员
本地化协调员的职责包括:
———与翻译或本地化服务供应商沟通,向其提供翻译或本地化的资料,维护版本控制;
———提供一个术语列表,或者提供以前翻译过的术语和不需要翻译的术语,比如产品名称就是不需
要翻译的术语;
———确保翻译的质量;
———参与制定合同框架,约束翻译供应商的服务质量;
———评估供方是否符合合同在技术方面的要求。
注:这个角色可以获得采购部门的支持。ISO/IEC/IEEE26512:2011描述了获取和提供用户文档服务的要求,包
括翻译和本地化服务。
8.3.2.14 翻译人员
翻译人员的职责包括:
———翻译文档,运用高水平的语言技能(包括源语言和目标语言)和翻译人员的专业技能;
———制定一份翻译词典;
———测试和评估翻译后的资料。
17
GB/T16680—2015/ISO/IEC26511:2011
8.3.2.15 发行人员
发行人员(或者发行协调员)的职责包括:
———构建各种介质的文档的最终版本,并提供给客户,需要时通过工具自动化完成;
———监督发布前的最后质量检查;
———确定文档的封面和封底,并添加到打印的文档上;
———确定元数据,并添加到电子文档上;
———与软件开发者联系,将需要的嵌入式文档集成到软件产品中;
———生产交付物介质,例如磁盘;
———实施发行资料的版本控制。
8.3.2.16 印刷协调员
印刷协调员的职责包括:
———与内部或者外部印刷供应商联系,利用印刷行业目前印刷技术和过程的经验和知识;
———确保样品和最终印刷品的质量,成本和及时交付;
———参与制定合约,约束印刷服务,评估供应商的服务是否遵循合同条款(除非采购部门或者内部
印刷机构提供服务)。
9 用户文档管理控制方法
9.1 文档编制测量
在对文档进行正确的估算、计划和安排的过程中,文档的测量起着很重要的作用,文档测量还可以
控制和改进文档的产品和过程。收集和分析文档的测量能帮助我们理解用户文档的质量水平、提高其
质量并对质量的改进进行量化。通过测量质量,文档管理者可以:
———了解质量水平是否正在改变;
———传授高质量技术(“成功的案例”);
———确定竞争者(“竞争分析”)。
测量的过程使用“Plan-Do-Check-Act”模型。文档管理者应计划如何测量文档,使用的方法是确定
测量的目标并定义要收集的关键测量。文档管理者应选取那些利益相关方认为重要的测量,进行文档
化,并考虑如何将其进行改进。管理者应收集、记录和分析测量,建立基线并确定其发展趋势。管理者
应用测量控制工作质量并进行工作改进。
文档和信息管理的测量应实用。实用的测量有下列特点:
———定义明确,使得每个人对其有一致的理解;
———具有一定的范围、有意义的值域和已知的斜率,也就是说测量结果的曲线形状是可以理解的;
———可以容易获得或值得获得;
———可以再现或重复;
———能够测量过程的结果和质量的重要指标。
示例:对于每1000个文字的书写错误,其范围可能是0(没有错误)到1000(每个文字都是错的)里可能的取值,值
域是整个范围,斜率是负数(数值越小越好)。测量是客观的、可以重复的,测量的对象是由权威机构指定的文字列表。
注:ISO/IEC15939:2007给出了更详细的信息。
9.1.1 用户文档产品测量
管理者对用户文档测量最常见的需求是能够估算文档的大小和编制文档所需的时间和资源。传统
18
GB/T16680—2015/ISO/IEC26511:2011
上用页数来测量用户文档的大小,会因文档的发布格式和每页内容量的不同而有很大的变化。现在,主
题数常被用来确定最后产品的大小,因为主题数是由被文档化的用户任务的数量来决定的。为了估算,
机构宜建立一个主题的典型长度(像在线帮助系统那样)。
在确定一个软件用户文档所含主题数时,宜考虑下列几个复杂因素:
———软件对机构战略上的重要性和软件功能的关键性,保持文档的最小化原则;
———在用户文档项目和软件产品中,重用或分享主题的可利用性;
———产生或重新产生的用屏幕截图作为插图的插图数量;
———从受众的角度来看,文档化的操作过程(工序)可能是相对复杂的或简单的。相对复杂的操作
过程(工序)可能需要几个主题才能被覆盖到;
———受众对软件功能中的概念和自动化的工作流的理解程度;
———受众对软件的基本导航技术的熟悉程度;
———对参考资料的需求程度,例如常见错误处理流程、错误信息以及没有内置在软件中的命令和代
码的列表。
软件内部函数的复杂性和数量同用户手册中需要的主题数没有很大的关系。
源文档的文字数量是评估翻译成本的一个常用测量指标(翻译后的语言的文字数量会发生变化)。
对文档修订的翻译,修改的文字数量是一个常用的测量指标。
间接的产品测量,可以评估可用性的特征,例如每个主题索引术语的个数、每个主题示例个数。
9.1.2 用户文档生产率的测量
估算文档的生产率对计划和控制文档是很重要的,然而,传统的每页小时数(或者最近使用的每主
题小时数)的测量受到许多不确定因素的影响:
———产品的简洁性很重要,像快速参考卡,其需要特定的设计,比编制一个长文档需要更多的时间;
———与要编写的文字数量相比,需要捕获或者开发的插图的数量;
———文档化信息的复杂度、编写人员的技能、对素材和软件的熟悉程度;
———可利用的领域问题专家、软件需求、软件系统;
———重用或自动更新的内容的比例,例如文档中使用变量改变产品名称;
———由于软件需求变更和文档化的软件功能的变更造成返工所产生的时间损失;
———包含在文档估算中的间接工作。例如内容管理系统和模板的建立和项目领导者(特别是敏捷
开发团队)的参与、SME的访问、软件测试和用户文档可用性测试。
管理者应制定基线生产率测量以及记录后续项目的生产率。管理者宜权衡这些不确定因素的影
响,估算生产率和新增任务导致的项目周期变化。
通过比较软件开发者或工程师的数量,组织经常会尝试去估算所需要的用户文档资源,这些估算方
法是自顶向下的并且是有参数的。因为本条中所列的这些不确定因素,这种估算常常有1∶5到1∶100
的不同,而且机构间是不能进行比较的。当用户文档人员更多地参与到软件开发团队的工作中以及支
持一个重要的新产品的时候,就需要更多的用户文档人员。而维护更新充分文档化的产品则需要较少
的用户文档人员。用户文档人员与软件开发人员的比例或者修订者和编写者的比例可以用作机构内部
的估算,但是要基于对相似产品的经验并根据项目的复杂性和人员的经验做调整。
9.1.3 用户文档质量测量
用户文档的质量特性包括:
———技术准确性;
———易于查找到所需要的信息,其中不会混杂不需要的信息;
———易于理解文档内容;
19
GB/T16680—2015/ISO/IEC26511:2011
———有效地使用插图和示例;
———易于使用的设计、包装或介质;
———易读的文字;
———语法的正确性;
———对独立解决问题的有用程度。
为了测量这些特征,传统上用户文档的质量测量需要跟踪缺陷的数量,例如语法或拼写错误或者软
件和用户文档间的差异。合理的质量测量与标准和要求一致,这些要求包括内容、结构和格式,并且假
设用户文档要求存在于文档计划之中。这些测量影响用户对文档的可靠性和质量的印象。可以用检测
列表来评估一致性。
然而,最合理的用户文档质量的测量是可用性测试的结果。管理者应确保文档被测试以符合其可
用性要求(7.3)。
生产完成后,用户文档质量可以通过分析组织服务平台的电话来测量。管理者宜通过分析服务电
话来确定用户文档和客服人员的文档的哪些部分需要增加、纠正和改进。文档的修订可以通过在线的
形式发布给用户,也可以通过更新客服人员的知识主题和过程。改进用户文档可以大幅度地减少服务
台电话的数量和持续时间,因此降低软件支持费用并且提高顾客对软件和组织的满意度。通过对分析
报告的问题,也可以改进未来项目的文档计划和其他过程。
用户满意度调查也可用作估计用户文档的质量并作为改进建议。
9.1.4 过程改进测量
管理者宜确定、记录和分析信息管理和用户文档管理过程的测量来改进过程。典型的测量值包括:
———文档策略和程序或操作指令所覆盖工作的比例;
———完成操作步骤所用的平均时间长度;
———增加顾客价值所用操作步骤的比例;
———直接应用到一个项目与间接应用到多个项目所需小时数的比值,称为开销;
———满足质量标准或符合标准系统、格式、风格和计划所需返工的工作量;
———按时或按预算完成的项目的百分比。
9.2 文档估算
管理者应记录资源估算的依据以及记录某项目所需资源的计算结果,并与实际值进行比较来改进
以后的估算工作。
估算开发文档所需的时间和资源宜用自顶向下和自底向上相结合的离散估算法来进行,两种方法
都需要至少知道初步的文档计划或WBS。
自顶向下的估算法比较本项目与其他相似项目。例如为一个系列的打印机编写用户手册时,可以
根据打印机产品线的前四个型号文档编制工作中的内容重用量和工作减少量,来估算该系列第五个型
号打印机文档编制工作所需的工作量。
在一个新工作中使用自顶向下估算法时,可以和以前的工作进行比较,需要根据项目的大小和复杂
度以及资源的可利用程度和水平进行调整。
自底向上估算法根据每个具体任务的估算计算出总的估算。估算宜与机构的基准生产率测量相比
较,例如与每主题的小时数或每插图的天数相比较。
当项目的预算不多时,管理者宜决定所分配的预算是根据自顶向下的方法还是根据自底向上的方
法估算出来的,其差距可导致文档项目范围的缩小。相似地,当项目提交的截止日期一定时,管理者宜
根据估算和初步进度决定提交日期是否可行。管理者可能需要修订估算以利用附加的或更多的经验丰
富的资源,如果资源有限,修订可能使项目的花费更大或使项目的范围缩小。
20
GB/T16680—2015/ISO/IEC26511:2011
执行一个试验项目是估算未知项目比较好的方法。编写者宜开发一个样本章条或较少的主题,并
记录所用的时间,管理者可将实际所用时间值作为基准来得到项目其余部分的估算值。
除了估算执行任务所需的资源(如6.2所列),文档管理者宜考虑外包服务所需的成本,例如翻译、
生产和复制、材料、设备、包装和运输。
当估算生产已打印文档副本的成本时,管理者宜做如下考虑;
———文档的页数;
———页面的大小;
———使用的颜色;
———特殊插图的准备;
———纸张的质量和类型;
———每个文档需要复制的数量;
———打印成本;
———装订和包装的成本,包括材料;
———发布成本。
10 管理控制在文档中的应用
10.1 目的和成果
管理者应对信息管理和软件用户文档的编制工作进行控制,以确保其符合计划和进度、保持在项目
的预算内、满足质量和可用性的目标。控制包括:
———执行测量;
———记录、调查并解决问题;
———采取行动以避免问题再现;
———估计请求的变更所产生的影响;
———调整行动方向以更正或减少目标和计划的偏离。
管理者应在项目重要的里程碑或者至少每个月定期地进行评审并准备进展分析报告。像用户文档
和相关组织的策略不断要求的那样,管理者应定期地对整体工作进行评审以确保所有的工作都是可行
的。对于如果继续投资,其缺点或风险超过其利益的项目,组织在合同允许的范围内,应将其取消或
暂停。
10.2 变更管理
管理者在软件产品和文档的生存周期内,应有计划地控制计划、记录、提交的文档和主题的重用和
修订。变更管理计划宜描述如下内容:
———控制信息的修订;
———对电子版和纸质版的文档进行存档;
———控制和发布正式批准的文档管理计划。
管理者应为可唯一标识的信息项和文档建立一个变更系统,使其接受变更控制。标识的数据宜包
括文档化的软件产品、语言、用户文档类型、版本和修订、发布的日期和状态(如初始状态或最终状态)。
按照组织对记录的存储、安全性、维护和备份的需求,重要的资料应被保存。
10.3 进度和成本控制
管理者应跟踪进度和资源计划或预算的执行情况。跟踪执行情况包括记录实际持续时间、实际使
用的资源、进度表中文档每个部分以及WBS元素或任务的完成情况。
21
GB/T16680—2015/ISO/IEC26511:2011
对于某些已经开始但尚未完成的主题,可以用变化的百分比来表示进度。更加严格的跟踪方法在
开始任务时指定固定的百分比(例如任务已完成20%还剩80%未完成、甚至任务已完成0还剩100%
未完成)。
当跟踪结果显示一个项目进度落后时,不宜为节省时间而删除进度中那些能够确保质量的活动,如
内容评审和可用性测试。管理者宜权衡费用、进度和质量之间的影响。
管理者通过比较项目的状态和基线的进度表与预算,掌握项目的活动是提前还是落后,是低于预算
还是超出预算。然而,这些进度或费用的变化不能反映项目执行的整体情况。
一般情况下,人们都期望低于预算,但如果花费比预算少是因为团队完成的工作量不足而落后于进
度表,那这个项目可能不会完成既定目标。相反地,如果项目的花费高于预算但团队完成的工作比计划
快很多,那么团队可能实际上会提前完成任务,且从总体上来讲不会超出预算。
可以用实现价值或预算的已完成工作量成本来更好地对执行情况进行测量。如果执行情况正常,
实现价值将等于实际已完成工作量成本。实现价值大于实际已完成工作量成本表明项目的执行情况是
令人满意的,实现价值小于已完成工作量成本表明项目的执行情况令人不满意的。
示例:一个管理者预计第一章可以在10个工作日内完成,每个工作日的花费是500元人民币(总共5000元人民
币)。第6天结束时,这个管理者根据已完成的材料估算出这一章已经完成了80%,按计划宜用8天来完成(10天×
80%)。实现价值是5000元的80%=4000元人民币,实际费用为3000元人民币(6天,每天500元人民币),实现价值
大于实际费用,结果表明项目的执行情况是令人满意的。
10.4 资源管理
10.4.1 项目沟通
一致性和团队成员间的及时沟通是非常有用的,可以对策略、目标和计划进行沟通,也可以评估风
险、获取项目情况、报告问题解决方案。有些机构内部存在一些限制,例如(虚拟的)项目组成员的地理
位置相距很远,这时电子通信媒体就显得很重要。
10.4.2 管理文档团队成员和供方
管理者应根据项目中确认的角色(示例见8.3.2),确定知识和技能的水平以达到他们满意的表现。
组织应雇用或选拔和培训员工以满足组织和项目的资源需求,或获取用户文档服务。管理者应就信息
管理部门职员的角色和责任的描述与他们进行沟通。管理者应保留所有员工表现的记录,作为以后项
目估算和个人工作分配的依据。
注:ISO/IEC/IEEEE26512:2011《系统和软件工程 用户文档需方和供方的要求》处理用户文档服务的供方的管
理控制。
10.4.3 管理翻译服务
翻译管理是需要平衡用户文档的准确性、时间要求和费用的一个特例。通过在项目一开始就对翻
译有所计划,管理者可以用下面的方法来节约成本并提高翻译的质量:
———选择采用根据图表表示的而不是根据文字表示的文档设计,并且避免插图中的文字标签转换
成图形图像;
———选择合适的输出格式,当翻译后的文字量比源文字量大时,有足够的空间(例如,将中文翻译成
英文);
———特别注意那些和源语言的阅读方向不同的语言输出格式(例如,将英语翻译成阿拉伯语);
———使用限定的词汇,以保持术语和语句结构的一致性;
———通过翻译服务,使得翻译词典可以重用;
———对材料的重用进行计划,从而仅对变化的词汇进行翻译;
22
GB/T16680—2015/ISO/IEC26511:2011
———为了避免重复劳动,当源语言的版本完全通过评审和测试后再安排翻译工作。
在翻译项目中,为了使项目按时竣工,需要对翻译、评审、测试和修订或改正进行严格监视和控制,
并进行额外的管理。
10.5 质量管理
管理者宜决定怎样取得和保持质量,和文档策略保持一致。
示例:用户手册可以是有几页纸装订的纸质版或电子版的,也可以包括由图表专家设计的插图,或者是可以在电子
设备上播放的视频。
管理者宜根据信息的重要程度和文档的用途建立内容、结构和版面的标准(例如:是经常使用的参考资料
还是初级培训教程),标准可以包含在文档管理计划、文档计划、模板或模型中。高质量的用户手册是:
———准确的;
———关键信息是完整的;
———清晰的;
———高效的,根据用户快速找到所需信息的能力来衡量;
———有效的,根据用户应用相关信息完成一项任务的能力来衡量;
———和用户需要相关的,提供满意的用户体验。
10.5.1 管理产品质量———评审和测试
管理者应在用户文档交付前确保其满足需求。用户文档典型的质量问题是不正确、不完整、含有不
必要的信息、使用不一致的术语、没有条理、难度相对于目标用户来讲过高、访问方式或导航不明确、对
指导性的资料来讲不是面向任务的。
注:ISO/IEC26513:2009《系统和软件工程 用户文档的测试者和评审者的要求》有详细的要求,确保产品质量通
过评审和可用性测试。ISO/IEC26514:2008《系统和软件工程 用户文档设计者和开发者的要求》描述了怎样
对用户文档进行结构化,以指导用户使用软件。ISO/IEC9003:2004《系统和软件工程 计算机软件》在
ISO9001~2000中的应用指南,可以作为软件用户文档质量的参考。
10.5.2 风险和问题管理
用户文档的风险可以影响一个用户文档项目或组织内部一组文档的内部进度、费用和质量。基于
组织的信息管理策略和项目的目标,用户文档管理者宜识别、评估、处理和监控风险。风险处理的措施
包括避免、优化、转移或保留(接受)风险。
———风险避免-选择不同的方法来消除风险;
———风险转移-采取一些步骤降低风险的严重程度;
———风险接受-判定避免或转移风险所需的费用大于如果风险转变成实际问题可能带来的影响。
注1:关于风险的讨论详见ISO/IEC16085:2006《系统和软件工程 生存周期过程 风险管理》。
除了管理文档项目的风险,文档管理者还宜注意到因为软件用户而引起的风险,还宜注意到可以减
少这些风险的方法,例如:通过包含警告和注意。
管理者应建立和实现用户文档的问题管理系统,建立和实现一个程序来发现和评审用户文档报告
的问题、为问题的严重性划分等级、确定问题的根本原因、解决问题以及当需要时修正组织的过程。
注2:当软件和用户文档同时开发时,一套综合的问题管理系统可以同时解决两方面的内容。
10.5.3 过程改进
当组织具有可重复的文档化过程时,有可能对其进行改进。管理者应在项目结束时召开评审会议,收
集成功过程的信息和过程改进意见。管理者应确保对这些改进意见进行记录和评审,并且使其得到实施。
[1] [2] [3] [4]
导航
