5 生存周期过程中的用户文档管理
5.1 软件生存周期中的用户文档管理
ISO/IEC12207:2008定义,用户文档管理是软件或系统生存周期中的支持过程。用户文档随着软
件架构设计过程逐渐形成初级版本,在软件详细设计、软件构建,软件集成,软件测试和软件维护活动中
根据要求进行更新。
注1:也可以是为先前发布的软件或者商业现货软件开发用户文档;
注2:ISO/IEC26515软件与系统工程在敏捷环境下开发用户文档中有更多关于用户文档开发和软件开发之间关
系的信息。
无论用户文档开发是不是软件生存周期的一部分,文档都有自己的生存周期,包括一系列的过程实
现阶段;设计和开发,生产和维护阶段。
用户文档管理应应用于文档生存周期的其他活动中:
a) 分析和设计,包括为项目文档设计做准备的;收集软件产品和用户的信息、任务和需求;基于这
些需求设计文档;
b) 开发和评审,包括根据适用性原则安排文档内容,通过编写文字和图形内容实施文档设计,在
指定的媒体上实施信息,编辑和评审文档的内容,评估用户文档和产品的其他部分;
c) 生产,包括文档的整合、编制、复制、包装和发布;
d) 维护,包括在软件产品的整个生存周期内,保持文档的准确性、控制文档版本,修改文档以提
高其易用性。
按照ISO/IEC12207:2008的要求,用户文档管理者应执行符合ISO/IEC12207:2008中6.3.6和
7.2.1的信息管理和软件文档管理的过程。
5
GB/T16680—2015/ISO/IEC26511:2011
注3:为了便于引用,附录B列出了这些过程的详细内容。
用户文档管理者应参照PDCA(Plan-Do-Check-Act)理论,执行如下活动:
1) 制定用户文档的策略和目标,准备文档管理计划;
2) 策划用户文档项目;
3) 监控用户文档项目;
4) 选择和实现文档编制所需的资源、工具和支持系统;
5) 改进信息管理和文档编制过程。
成功实施信息管理和软件文档管理可产生如下成果:
———形成策略,以确定软件产品和服务生存周期中需要编制的文档;
———确定软件文档开发过程中所采纳的标准;
———确定过程或项目中编制的文档;
———描述、评审和批准所有文档的内容和目的;
———按照确定的标准,完成文档编制并确保其具有可用性;
———按照确定的准则,维护文档。
5.2 组合管理和内容管理
上条是从单独产品的单个生存周期的角度来阐述软件用户文档管理过程的,例如一个单独的用户
手册、帮助系统或者文档集。本条着眼讨论用户文档管理者管理多个项目和产品的情况。因此用户管
理涉及如ISO/IEC12207:2008中6.2.3所述的组合管理过程的运用:
项目组合管理过程的目的是启动和维持必要的,足够的,适合的一些项目,以满足组织的战略目标。
这个过程需要投入足够的资金和资源,并批准创建所选项目的负责人,并不断地对项目进行资格验
证,来对是否继续投资的决策做出解释。
成功实施项目组合管理的成果如下:
———商业机会,投资和必要性是合格的,有优先级的,有选择的;
———每个项目的资源和预算是明确的,合理分配的;
———项目管理的责任和授权是明确的;
———项目满足协议和利益相关方的需求;
———项目不满足协议和利益相关方的需求时,会被重新调整或取消。
用户文档管理者应执行文档项目的组合计划,并与组织的整个组合计划保持一致。
为了支持用户文档组合,并保持一致性,内容管理是一个有效的方法,创建和格式化有相似信息主
题的多个文档时,它可以避免重复性工作。内容管理分离了信息产品的内容和输出格式,从某种意义上
说,内容管理是在信息资产上应用组合管理,而不是生产软件产品或用户文档。
软件用户文档管理者应制定、实施和维护一个内容管理策略。内容管理策略应利用被管理的内容,
指定有优先级的可重用内容的类型,以及有优先级的输出项(文档)的类型。
内容管理策略可以定义内容管理过程和系统的责任和授权。可以识别潜在的利益相关者和内容使
用者,包括本地化或者翻译的内容的使用者。可以建立标准用来判断哪些类型的内容需要被管理和
维护。
内 容管理策略不指定任何特定的内容管理系统或者文档编写工具。
注:达尔文信息分类体系结构[TheDarwinInformationTypingArchitecture(DITA)]是一个创建和管理文档的规
范,它建立了创作过程中的内容重用机制。
5.3 信息管理策略与方针
用户文档管理计划需要描述任务的关键信息:谁来做? 使用哪些信息源? 什么时候做? 在哪里做?
6
GB/T16680—2015/ISO/IEC26511:2011
使用哪些工具? 在管理者制定项目详细计划之前,需要一个信息管理策略:这项工作是否需要做? 每一
个方面需要做到什么程度?
管理者应建立一个信息管理或者用户软件文档管理策略。策略描述用户软件文档如何支持组织的
目标以及服务客户,确定产品和服务的优先级。策略制定宜与用户文档利益相关者(那些对文档有效性
感兴趣的独立个人或组织)进行协商,利益相关者可能包括高层管理人员、项目负责人、客服人员、客户
和业务分析人员。
用户文档策略的一个重要理论是最小化原则。既然不能文档化每个软件产品的每一个细节,那么
用户文档管理者就需要从策略性的角度,按重要性去支持用户、客户和生产组织的需求。最小化原则意
味着用户文档宜包含关键信息和用户完成主要任务需要的信息。用户文档宜是面向任务的,而不是覆
盖软件内部结构的每个细节。软件文档编制不宜将时间和工作集中在那些用户通过软件界面就可以很
容易发现和理解的软件功能上。按照最小化原则,用户文档没必要企图说明软件的每一个功能和每个
可能的路径。
用户文档宜是面向受众的。受众可能是经理、分析师、办公室人员、没有软件技能的专业人士、软件
维护人员等。由于工作任务的不同,他们对文档有不同层次的细节和展示的要求。作为用户文档的信
息管理策略的一部分,文档管理者宜计划信息重用和调整(内容管理)方案,以便有效和有效率地服务于
受众。所以文档计划宜说明为不同用户提供不同类型的信息。
信息管理策略宜符合文档制定方针。文档制定方针由高层管理提供并支持,为所有决策者提供指
导。方针提供广泛意义上的指导,不是详细的描述做什么和如何管理和编写文档。宜建立正式的、广泛
公开推广的方针,并且与受方针影响的每个人进行沟通和协商。
文档编写方针应确定采用哪个文档编写标准。相关信息的存储、记录管理、展示标准和约定需要与
协议和规定保持一致。宜尽可能的采纳已有的标准,没有适合的标准时,宜编写标准和指南。
用户文档策略,方针和标准宜能够使管理者确定以下内容:
———需要哪些文档类型;
———提供多少个文档;
———包含什么文档;
———要达到什么样的质量水平;
———文档什么时候完成编制;
———如何存储、维护和传递文档。
当信息管理策略已经建立,并且估算了组织资源和项目的花费和预期收益,用户文档管理者宜将策
略应用到:
———根据可用资源和限制,评估实现项目目标的可行性;
———按重要性排序即将开始的项目;
———建立标准决定哪些项目需要执行。
6 文档管理策划
6.1 文档管理任务的WBS
通过定义项目元素,项目WBS是有效的计划、评估和报告项目的基础。WBS宜被用来评估每个元
素的时间和花费,也用来跟踪已用的时间和花费。完整的WBS是项目初始评估,持续报告,纠偏,以及
计算可能花费的一个参考框架。管理者应在发布的信息范围内,定义每个文档项目级别或者元素级别
的WBS。WBS中文档元素的层数依赖于任务的范围和跟踪花费、进度和技术质量的详细程度。WBS
中“元素”可以是:
———文档类型,例如教材、参考资料和培训文档;
7
GB/T16680—2015/ISO/IEC26511:2011
———需要文档化的产品;
———文档项目或者文档项目集;
———发布的文档,例如用户手册、帮助系统;
———文档的翻译版本或本地化版本;
———文档元素(主题、章条、标题、插图)。
通过WBS元素的进一步细分,可以确定适当的花费和任务类型。WBS元素需要的任务类型:
———项目管理;
———文档设计;
———受众分析;
———作为学科专家提供信息;
———信息收集和研究;
———写作;
———编辑;
———插图;
———评审;
———修订;
———易用性测试;
———产品服务。
为了与组织方针保持一致,工作任务也会包含基础设施的支持,他们被分配到几个WBS元素中,
例如:
———整个策略计划;
———组织和项目的启动;
———维护和管理一个内容管理系统和版本控制;
———生产环境;
———信息发布(例如通过物理拷贝或者互联网在线访问);
———人力资源和技能开发。
6.2 用户文档编写计划
管理者应制定和维护用户文档编制计划,计划中包括:
———确定用户文档管理和技术活动的范围;
———确定项目的任务和交付物;
———建立项目任务进度表;
———确定完成信息管理和文档任务所需的资源。
文档管理计划(第7章)包含进度表。根据正在进行的工作的复杂性和数量,每个文档都可能有一
个独立的开发进度表,和软件产品其他部分的进度保持一致,再合成一个总的计划。因为某些活动的复
杂性,所以需要为用户文档测试、用户文档生产、本地化和翻译以及文档维护制定一个详细的计划和进
度表。
制 定一个用户文档任务的进度表包括下面这些步骤:
———识别和描述要发布的文档;
———为文档编制工作定义WBS;
———确定关键里程碑,截止日期和组织约束;
———建立和WBS保持一致的主要任务;
———确定任务和活动;
8
GB/T16680—2015/ISO/IEC26511:2011
———估算活动的持续时间;
———建立任务和活动之间的依赖关系;
———确定每个活动所需的资源;
———检查资源是否过度消耗;
———确定关键路径。
确定活动的范围后,管理者宜通过检查那些执行和管理项目所需的资源(人、架构、工具和信息源)
是否是可用的、充分的和适当的,以确保项目的可行性。
确定了文档进度的关键路径后(项目可能的最短工期),管理者可能需要在批准和执行计划表之前
对它进行修订。例如,作为利用相同资源的所有项目的主进度表的一部分,这个项目的进度表可能需要
进行修改。如果文档不得不比计划提早完成,可能要减少文档覆盖的范围或者增加一些任务需要的
资源。
文 档进度表应包含评审,测试,修订和批准提交物的时间。文档计划应清晰的描述评审和批准提交
物的责任人。
注1:管理者宜在任务的最后安排介绍性和概念性的主题任务,这样就可以应用在准备其他主题时积累的软件和用
户知识。
文档计划和评估中宜包含的用户文档项目的典型任务可以分成如下几类:
———确定目的和受众的相关任务;
———设计任务;
———开发任务;
———翻译和本地化任务;
———生产任务;
———变更管理和维护任务。
注2:这些任务各个方面的详细要求包含在标准ISO/IEC26514:2008中。
6.2.1~6.2.6列出基于这些标题的典型任务。
6.2.1 确定目标和受众
确定目标和受众的一些典型任务是:
———获取软件和软件开发项目的目的和目标;
———创建出版物项目的目的和目标;
———进行受众研究-由软件或者文档开发者或者其他组织;
———获取文档或者软件的客户说明;
———计划和开展客户研究;
———在用户的工作环境中和他们进行交流并观察他们的工作;
———分析用户需要或想要执行的任务;
———建立项目需求,包括项目的目标、动机和边界;
———获取需要的资源;
———获取需要的工具;
———定位供方并进行协商;
———学习如何使用新的内容管理或者编辑工具和系统;
———准备、评审和修订信息管理计划;
———进行项目的管理评审,包括人员、进度、工作和花费;
———评估项目的经验教训和过程改进活动。
9
GB/T16680—2015/ISO/IEC26511:2011
6.2.2 设计任务
典型的设计任务如下:
———收集软件信息(软件开发人员宜提供信息给文档编写者,并回答他们提出的问题);
———评审现有信息主题的适用性并重用;
———详细描述用户需要完成的任务;
———熟悉软件(最好的途径是使用软件);
———描述文档或文档集的结构;
———编写文档内容说明书或者详细的、带注释的纲要;
———设计文档格式和表现形式,或者选择和应用一种样式模板;
———指定文档的编写和发布系统,也就是使用的媒体;
———指定文档的接口设计;
———重新设计满足用户需求的可发布的信息;
———转化现有的文档内容,变成一致的,可重用的主题;
———评审和修订文档计划。
6.2.3 开发任务
典型的开发任务如下:
———编写文字主题;
———创建插图;
———编辑文字内容;
———建立电子文档系统;
———提供特定的辅助特征;
———管理工具、支持创作和内容管理的工具和系统;
———提供版本控制;
———评审文档的技术准确性;
———评审电子文档的系统特性是否能正确操作;
———评审插图的风格和质量;
———进行最终版的编辑工作;
———进行法律相关内容的评审;
———识别关键字并生成索引和目录;
———在每个计划的测试阶段测试文档,包括可用性测试;
———在每个技术评审阶段,执行文档评审。
6.2.4 翻译和本地化任务
典型的翻译和本地化任务如下:
———选择一个翻译和本地化服务供应商;
———准备目标语言的专业术语词典;
———给翻译者提供源语言的文本和图形文件;
———翻译或者本地化;
———编辑和评审已经翻译的和本地化的文档版本;
———更新翻译词典。
10
GB/T16680—2015/ISO/IEC26511:2011
6.2.5 生产任务
典型的生产任务如下:
———组合要发布的文件,主题或者章条;
———准备用于发布的可印制副本或电子文件并打印输出;
———检查打印质量;
———检查数字媒体质量,例如DVD和CD等;
———安排组装、发布和分发;
———协调文档和产品的打包和运送。
6.2.6 变更管理和维护任务
典型的变更管理和维护任务有:
———收集用户或者客服反馈的文档错误并分析这些事件报告;
———由于软件变更或者文档错误而更新文档;
———评审和重新测试变更后的文档;
———维护文档和信息主题的版本控制;
———根据组织方针和安全性和私密性的要求,存档所有必要的项目资料;
———根据组织方针和安全性和私密性的要求,处理所有不需要的、无效的、没有经过验证的信息。
[1] [2] [3] [4]
导航
