7 用户文档计划
7.1 用户文档管理计划与文档编制计划
本条主要讨论用户文档管理计划和用户文档编制计划的内容。尽管术语名称上很相似,但是在本
标准中,两者是有区别的,主要是计划的范围和类型不同。文档管理计划覆盖一个组织执行信息管理过
程的所有工作,很有可能是开发一个多用户多版本的文档产品。文档编制计划的范围会小一些,包括单
独文档或文档套件的项目计划,通常也包含文档编写规范。
本标准中,为了便于参考,每一个计划都要像一个单独发布的文档那样来描述。然而,如果计划是
不发布的,但是在版本库中作为参考资料,也应考虑一致性,这些计划被分割成独立的文档或卷,或者和
其他信息项合成一个文档。计划标题和内容中的术语不需要与本标准一致。下面列出的文档(信息项)
的内容列表并没有指定其标准的顺序、部分结构或者章条标题的列表。
本标准中的动词“包括(include)”表示(1)给出了信息,或者(2)列出了信息的参考资料。
一个计划应包含下面的元素:
———发布日期和状态;
———范围;
———发行机构;
———适用的政策、法律、标准、合同、要求和其他计划和程序的参考资料;
———审批授权;
———技术和管理评审和报告的方法;
———其他计划,进一步补充计划细节而产生的计划或任务描述;
———计划的活动和任务;
———工具、方法和技术的确定;
———进度表;
———预算和成本估计;
11
GB/T16680—2015/ISO/IEC26511:2011
———资源以及资源分配;
———职责和授权,包括高级责任人和直接责任人;
———各方之间的沟通接口;
———风险和风险识别、评估和转移活动;
———质量保证和控制测量;
———环境、基础设施、保密性和安全性;
———变更流程和变更历史;
———终止过程。
7.2 文档管理计划的内容
管理者应制定一份文档管理(或信息管理)计划,计划中定义和描述信息内容管理和文档编写的过
程。文档管理计划展现了生存周期中,一个组织打算如何实施信息管理或者软件用户文档管理的活动。
除了7.1中确定的通用内容,文档管理计划还宜包含如下信息:
———信息管理策略以及和整体组织战略的关系;
———描述用户所需的电子版和打印版信息的授权、开发、评审、存储、通信和维护的过程和相关
活动;
———确定信息获取,重用和生产的过程;
———与整个组织方针相一致的资源,角色和责任;
———内容管理或重用策略与版本控制(文档配置管理);
———确定用户电子版或打印版文档的结构、格式和风格的标准、指南、模型或模板;
———方法和工具;
———文档开发过程中实施的质量控制;
———确定信息开发、评审和批准过程中典型的进度表和标准的持续时间;
———确定用户文档编制项目的标准测量和估算方法;
———谁将接收或访问受限的信息;
———保留信息的策略和用户文档版本控制、变更控制和维护的规定;
———过程评估和改进的规定。
7.3 文档编制计划的内容
管理者应制定一个文档计划,描述项目中要开发的文档项,除了7.1确定的通用内容,文档编制计
划还宜包含如下内容:
———确定用户文档需要覆盖的软件产品;
———每个文档或者文档集的理论依据或目的(指导性的或者供参考的)以及范围;
———每个文档的预期受众(用户属性),例如以教育水平、技能和经验为特征进行描述;
———要获取、重用或开发的文档和信息以及他们的预期来源;
———用户文档的可用性要求;
———每个文档的媒体和输出格式的控制模版和标准设计;
———根据文档主题、插图、单词、页、错误信息、命令或者其他参数的个数估计用户文档的大小;
———用户文档的大纲,目录或者主题列表;
———文档开发和生产过程中的方法和工具,包括在软件开发过程中将软件变更信息及时传递到文
档编写者的方法;
———角色和职责;需要的技能水平,团队成员选拔计划可以作为可选内容;
———文档开发、评审、批准通过和发布的进度表,包括对软件产品开发进度表或其他文档项目的
12
GB/T16680—2015/ISO/IEC26511:2011
依赖;
———翻译和本地化用户文档的相关计划;
———确定具体交付物,例如打印版的份数(如果适用),磁盘和文件格式(包括软件版本),提交物发
布的位置。
作为可选的,文档编制计划也可以包含每个文档的安全或保密性等级,谁能接收和访问这些受限的
文档。
注1:ISO/IEC/IEEE26512:2011包含了用户文档要求的额外详细信息。
文档的易用性需求独立于软件的易用性,可以包含如下指标:
———用户熟悉文档内容所需的时间,特别是在提供了多个文档的情况下;
———用户理解文档结构并学习如何使用它的时间;
———一旦用户熟悉文档,查找到所需信息的时间;
———文档的可行性和用户根据文档的指导完成一个指定任务的时间。
注2:ISO/IEC26513:2009提供了用户文档测试的要求,包括可用性测试。
文档编制计划宜在文档编制工作之前准备并得到批准,确保各个方面同意其目标和要使用的方法。
计划被批准后,宜尽可能广泛的发布;发布对象宜包括文档开发团队的所有成员,也可以包括文档需方
成员和转包商成员(例如印刷商、排版人、翻译者)。如果文档编制计划发生后续变更,管理者应确保所
有受影响的利益相关人员都得到变更通知。
文档编制计划的示例参见附录A。
8 项目启动
8.1 授权、规程和规范
根据组织的方针策略,用户文档项目应由管理者、产品负责人或者负责信息管理和文档编制的高层
发起人授权。项目涉及的团队成员宜能够访问授权信息,包括项目的目标和范围。
管理者应确保文档评审、可用性测试和版本控制(配置管理)的过程被文档化。过程宜包括使用信
息管理和内容管理系统来创建、变更、审查与协作、存储、查找、检索和传递信息,也包括管理系统的
访问。
实 施一系列过程的最大难题是获得参与人员的认同。高层管理者宜支持这个项目,可以通过思想
动员、培训等手段与过程中的参与人员达成共识,但是一个更有效的做法是让相关人员参与过程的制
定。文档编制团队成员可以参与决定实施什么样的过程并将这个过程文档化。
管理者应确保编制相关文档的开发规范,使得相关文档易于使用,有一致的风格和格式。风格一致
的软件产品、产品包装和用户文档对用户是非常有益的。
一份文档风格约定应标明如下内容:
———标准或规范的词汇(尤其是翻译和本地化过程中);
———产品指定术语的拼写;
———组织标识和软件产品标识的使用;
———标题或者主页的设计;
———页面或者屏幕布局;
———文本和各级标题的样式;
———缩略语的使用;
———大写字母的使用;
———列表样式;
———操作过程(工序)的风格;
13
GB/T16680—2015/ISO/IEC26511:2011
———软件示例代码风格;
———写作规范;
———图表样式;
———警告、提醒和注释的表示形式。
规范可以说明数据元或分类的使用。
注:ISO/IEC26514—2008包含用户文档表现格式和样式的详细要求和指导。
8.2 基础设施
管理者应配备相应的基础设施资源或者服务,用于信息的创建、变更、展示、评审和协作、查找、检
索、传递和发布。信息的存储和保留应易于获取和读写,防止受破坏、恶意修改和丢失。
注:信息的存储介质,位置和保护宜根据指定的存储和检索周期,组织的方针策略,协议条款和立法来决定。
文档管理计划应指明需要的基础设施系统(硬件设备和软件)。
8.3 信息开发团队
8.3.1 角色定义
管理者应定义好一系列计划要执行的用户文档活动需要的角色,例如信息和文档的设计、开发和生
产活动。管理者应确定每个角色的职责、技能和专业知识。
有两种安排角色执行任务的方式:
———职能型:一个文档团队负责一个或多个正在持续开发的软件产品的文档编制工作;
———项目型:文档团队成员被分派到项目团队中,完成其文档编制工作,直到项目结束。
角色不是单单一项工作,根据任务的大小,可能一个人担任多个角色,也可能多人担任一个角色。
一个小规模的文档编制项目,一个人可能承担所有必要的角色,但可能不需要所有的角色。一些大规模
的项目,可能涉及多人担当一个角色,而且需要所有的角色。非常大规模的项目可能还需要额外的支持
角色(例如,人力资源专家,行政管理支持和IT支持)以确保团队顺利的完成任务。
注1:ISO/IEC26515描述了一个敏捷开发团队需要的用户文档角色。
组织应将完成项目所需要的资源进行分配。
组织应确保具备所需技能和专业知识的人充当这些角色。一些角色可以分配给和文档开发有关的
人员,但是他们不属于文档编制团队,不需要向文档编制团队汇报工作。
示例:提供产品信息的领域问题专家(SMEsubject-matterexpert)或者检查关键功能正确性和覆盖率的技术评审人
员,他们都不属于用户文档编制团队。
用户文档团队的成员最好能熟悉相关学科知识、业务或者软件所需支持的功能和承担的任务,这些
有助于他们准确的表达软件的概念和功能,帮助软件使用者完成任务。但是,信息设计人员或编写人员
也没有必要成为领域问题专家(SME)。
同样地,信息开发团队的成员只需要在工作中能够使用基础设施工具即可,管理者没有必要要求团
队成员在某个指定工具上具有丰富的经验。编写者学习一个新工具和技术的能力比他在某个特定工具
的丰富经验的能力更有价值。同样道理,编写者能够快速学习新工具,也就能快速理解新软件并将其文
档化。
注2:当用户文档服务对象是一个短期项目或者紧急任务时,选择对特定工具比较熟悉的团队成员是比较适合的。
用户文档团队成员的能力和责任可以分为三个级别,初级,中级和高级。下面有关编写者职责水平
的描述可能同样适合其他角色。
初级编写者在全面指导下进行工作。工作内容涉及写作技能和原则的运用,需要一定的主动性和
判断。这个水平的人员经过相关培训,有良好的沟通技巧。但是缺乏或没有信息技术方面的实际工作
经验。随着工作经验的积累,对他们的审查和指导逐渐减少,而是希望他们能够更多的发挥主动性,独
14
GB/T16680—2015/ISO/IEC26511:2011
立的判断和思考。这个水平的人员可能需要和辅助人员互动并给他们提供工作指导。
编写者或者中级编写者在有限的指导下完成编写和相关活动。这个水平的人员应该经过相关培
训,能够胜任广泛的技术文档编写工作,具有丰富的经验。根据项目的大小和复杂性,他们可以作为个
人,也可以作为团队中的一员,或者团队的领导者来完成工作。
高级编写者在有限的指导下,承担技术性文档编写任务,需要具有相当大的原创性,独立性,主动性
和判断能力。这个水平的人员应该已经熟练掌握信息开发的技术和原理,并在多个项目中成功运用。
他们宜在时间,预算和形式限制下展示他们监控,控制和评估变更以及创新的能力。他们的工作包括指
导文档的开发、修改和维护。
工作描述可以基于角色列表和对应的技能水平。管理者可以协助编制工作描述。管理者宜就需要
的角色及拥有的技能与负责招聘的人员进行沟通。
8.3.2 用户文档编制的角色示例
一个指定团队所需要的角色根据团队要执行的任务而定。
组织中的很多角色都需要具备一定的责任和能力,例如:
———能够与产品开发者,教学设计者,技术支持人员,培训人员和其他相关人员高效的合作;
———接受并热衷于对传统工作方式的改变。
接下来的内容中定义了每个角色的职责。管理者宜确定组织和项目需要的角色,确保团队每个操
作的方方面面都被覆盖到。
8.3.2.1 管理者
管理者的职责包括:
———确定每一个文档项目和任务的范围并对所需工作进行估算;
———制定计划,并在整个信息开发生存周期中执行计划;
———安排任务;
———选择员工并将任务分派给员工;
———测量和监控项目进展情况,对变更实施控制;
———向利益相关方(包括管理层)汇报项目进展情况;
———管理风险;
———解决团队成员之间以及和其他团队成员之间发生的问题;
———指导和支持团队成员,与所有利益相关方进行互动沟通,发挥高水平的人际沟通技能;
———与信息架构师和设计师沟通,平衡需求和成本。
注:对文档进行管理需要了解文档开发过程中涉及的任务。即使是在文档维护过程中,项目管理技能也是必要的。
8.3.2.2 团队领导者
团队领导者的职责包括:
———指导编写者和插图设计者,确保他们按照进度和需求进行工作,发挥高水平的人际沟通技能;
———向管理者不断地提供项目监控信息。
8.3.2.3 信息架构师
信息架构师的职责包括:
———收集组织需求,用户需求,预算和其他作为项目输入的信息;
———制定文档编写策略,例如采用最小化原则;
———计划和记录不同受众所需的信息,形成需要编制的信息文档集;
15
GB/T16680—2015/ISO/IEC26511:2011
———同文档编制团队(特别是信息设计师)和组织其他成员沟通文档编制策略,发挥高水平的人际
沟通技能;
———根据业务需求和相关约束,发布较好的信息设计;
———与管理者协作,平衡需求和成本。
8.3.2.4 可用性设计师
可用性设计师的职责包括:
———与信息架构师和信息设计师协作,确保计划编制的文档具有可用性;
———安排和分析文档及相关产品的可用性测试,应用可用性的理论和实践知识;
———分析文档与相关产品是否符合健康和安全性方面的法规、原理和实践。
8.3.2.5 平面设计师
平面设计师的职责包括:
———设计文档的整体外观和感觉;
———设计开发文档模板,包括封面设计,需要时可以借助文档工具;
———与插图设计者协作,确保符合图形设计标准;
———需要时,可借助图形设计工具制作文档中需要的图形元素。
8.3.2.6 信息设计师
信息设计师的主要职责包括:
———进行文档受众分析;
———为独立文档和文档集开发文档计划;
———将组织文档编制策略应用到信息设计中;
———与管理者协作平衡需求和成本;
———和文档编制团队成员沟通信息设计;
———监控文档编制工作,确保其按计划执行。
8.3.2.7 编写者
编写者的主要职责包括:
———与领域问题专家交流,理解将要被文档化的资料信息;
———根据文档计划中指定的结构编写文档;
———根据编写规范,高水平的发挥书面语言表达技能;
———与插图设计者协作完成图形制作;
———与评审人员和领域问题专家协作,识别一些不清楚的地方和错误;
———在履行这些职责时,发挥高水平的人际沟通能力;
———凭借文档编写和文本处理工具的背景知识,培养熟练使用指定的内容管理工具的技能。
[1] [2] [3] [4]
导航
