单独来看，虽然在线帮助和使用说明书编制相对较快，但在发布几个产品版本和编制工作短暂停滞之后，工作量就会出现有机增长：因为在线帮助和使用说明书是各司其职的。由于结构各不相同，内容更新和再利用时，也会给技术文档工程师造成困难。而且冗余内容和时效性差异也会让用户感到迷惑。尽管各种问题和可能的解决方法都显而易见，但编辑人员往往缺乏让软件文档适应未来的使命感和远见。
本文主要针对希望或必须在只使用可用工具并无顾问协助的前提下完成这类项目的小型团队和个人，希望激励技术文档工程师对文档结构化改造进行必要展望。实际上，这可能意味着将非结构化软件文档（由 PDF 版使用说明书和 CHM 格式在线帮助组成）转化为一个集成化主题架构。
下面每个章节分别介绍一个项目阶段，这些项目阶段可能贯穿在整本书的字里行间。因此，首先要确定各个阶段的相互关系和正确顺序。
插图：按主题架构编辑软件文档的工作步骤 来源：Kai Weber
为让文档适应未来需求，很多软件公司在首次着手结构化文档编制时会感受到两大惊喜： 一是，如果想让文档具有可持续的整体性结构，需要在确定工具和具体内容之前推进很多概念性步骤。若省掉这些步骤，后面将会付出更高代价。通行法则与软件开发相类似：如果在规划或设计阶段纠正错误，成本要远低于在产品中或交付给客户后纠正错误。 二是，概念性步骤完成后再选择文档系统或帮助工具。没有任何工具可以弥补方法或流程中的缺陷。客户需求和自身战略目标永远比软件功能和厂商承诺重要。
在启动这样一个项目之前，最重要的决策在于该项目有哪些参与者。要确保项目成功，至少需要保证所有技术文档工程师和预算管理员参与其中。技术文档的其它“相关者”（包括培训师和产品经理）至少应该自始至终了解项目及其进展情况。
明确指导方针并确定用户类型
与企业方针一样，指导方针应给所有参与者指明目标和方向。在改造项目进行过程中，指导方针帮助大家始终铭记自己的远大目标。在项目结束时，指导方针可为测量最终成果和改善程度提供支持。
指导方针阐述最终文档的预期目标，即可以为谁以什么方式带来何种效用。指导方针也以间接方式影响组织工作，即由谁如何编制、维护和提供该等文档。指导方针的表述不必过于刻板或详细，且必须为其它项目阶段的战略决策留有余地。
指导方针可以是概括性的，比如：“让用户在正确时间正确格式下找到相关信息。”在后续过程中，则需明确有哪些用户类型，他们需要哪些信息以及必须以什么格式提供这些信息。指导方针本身不能出错，并且必须在若干方面起到协助作用：指导方针必须服务于客户和用户，使其可以在相应文档的帮助下更好地操作产品。此外，指导方针必须服务于公司，使其通过这类经过优化的产品获得竞争优势，比如大幅提高产品质量。 指导方针有助于参与者在公司内部进一步夯实技术文档的作用和意义，尤其必须帮助项目参与者在后续阶段设定有助于达到既定目标的正确标准。
确定目标群体和输出格式
首先，根据指导方针确定文档的目标群体和输出格式。目标群体扮演着用户角色，必须对其进行精确定义，以便决定哪些内容对哪些人具有重要意义。除最终用户之外，是否还应考虑系统管理员或开发人员（这些人员都有各自需要而对其他组别无关紧要的信息）？文档中是否包含面向同事的内部信息？
在确定目标群体时，可以采用人物角色形式。即为每个目标群体设计一个虚构的、具有代表特色的简短介绍，进而使用户角色更加形象和具体。最终用户 Elke 拥有十年职业经验并在工作中使用这款软件。她非常了解这个行业和类似产品，并期望这款产品能够为她的工作提供有效支持。新手 Norbert 出于个人兴趣使用这款软件。他希望能够快速上手，而不因功能广泛而感到挫败。Stefanie 是一位经验丰富的系统管理员，她必须知道这款产品在安装时有哪些系统要求以及与哪些软件版本相兼容。因此，指导方针应反映目标群体的最主要需求。
输出格式取决于人物角色的需求。比如，最终用户 Elke 需要与语境相关的在线帮助，以便其迅速了解应该使用哪个功能或设置。新手 Norbert 希望获得入门帮助，甚至可能需要有助于其快速熟悉产品的视频。系统管理员 Stefanie 需要一个可在产品以外快速且可靠使用的安装指南。综上所述，此类输出适用格式为 PDF，因为PDF可以轻松显示内容并进行打印。
确定信息模型并立足于用户类型
接下来，是在目标群体和输出格式的基础上确定信息模型。信息模型指的是不同输出格式下各个文档组成部分的抽象结构。此外，信息模型不仅是有助于保持文档一致性的模板，其主要意图是使段落层面以上各级内容的自动访问和再利用成为可能。 信息模型，比如可描述语境相关现场帮助条目的结构，可能首先有一个关于该现场意义和意图的介绍语句，然后是对允许数值或现有数值及其影响的说明。如果可能，接下来是故障排除提示和相关信息参引。这种抽象化概念性工作可以简化对专业最终用户 Elke 及其具体信息需求的设想。
在入门帮助方面，这种模型可以对入门教程的结构进行说明，即它可以如何帮助新手 Norbert。只需简短介绍即可说明后续内容将介绍哪些工作步骤和功能，以及在哪里可找到进一步消息。
所有指南或教程都遵循标准结构，比如：
- 功能目标和意图
- 前提条件（如有），比如必须事先执行哪些步骤
- 分步指南
- 指南预期目标
- 故障排除（如果适用）
- 后续步骤（如有）
信息模型的细节深度主要取决于对文档自动化的要求。如果有谁想在不久的将来引入内容管理系统 (Content-Management-System)，则需要一个按上述列表定义段落层面以上各级结构的精确模型。现有的 DocBook 或 DITA 等开放式标准都是值得推荐的范版。在全部重新开发之前，应检查这些现有架构是否都不适合自己的项目，有时可能需要进行一定的省略或调整。
确定流程并更好地规划技术文档
接下来是确定流程，即自己所在组织如何规划、编制、维护技术文档，并将其以输出格式交付使用。依据已知目标群体和格式以及信息模型描述公司内部各角色之间的互动关系。 比如，技术文档工程师需参与新型产品功能的参数设计过程，以便于其编制该新型功能的文档。产品管理员需对文档说明进行验收，由技术文档工程师将其转化为实际内容，由一名测试员对其进行功能检测，由产品经理对其进行专业检测，由一名审稿人对其进行语言检测，最后正式发布。
这是最常采用的过程链。整个过程按照标准化形式推进，让技术文档规划变得更加容易：结合用户角色、输出格式和信息模型，在产品扩展之初就已经可以相对准确地预测需要编制哪些文档内容。具体而言，有时可能需要编制一个背景说明，此外还需要两个全新的工作步骤说明，还需要对四个现有步骤和一个教程视频进行调整。相对于大批量编制新的功能文档而言，上述时间和精力的规划更加简单、精准。当标准化流程具有可规划、可测量和可重复三大特征时，可以在很大程度上促进文档编制工作。
拟定编辑指南并完成概念阶段
编辑指南确保语言一致性。如果已经拟定了编辑指南，最迟可在确定信息模型之后对其进行修改，因为信息模型往往也会对语言表述造成影响。比如，编辑指南有助于明确有待界定的特定用户称谓和语句结构，当然也有必要对不同的用户角色采用不同称谓。编辑指南存在疑问时，应迅速向技术文档工程师和审稿人提供明确答案。因此在确定流程之后，必须确保所有参与者都获得并可使用编辑指南。 当然也可以直接使用现有编辑指南。比如，如需创建 Windows 软件的文档，可以使用 Microsoft Manual of Style 的编辑指南。仅在特殊情况和不同政策要求下，需要额外拟定。
至此，这个旨在让软件文档更好的适应未来项目的概念性阶段全部结束。此时，所有参数都已明确，可以开始具体实施环节。但到目前为止的所有参与者必须清楚地知道，他们的大部分工作都具有隐蔽性，并且后续人员只能部分了解或在某些情况下了解其工作。因此，在具体实施环节中要始终保持谨慎：一方面，必须阐释、探究以及捍卫先前决策。另一方面，如果人员角色不符合实际、输出格式已过时或流程不兼容，则必须修改决策。
引入按主题撰写并准备数据迁移
在第一个月里，引入按主题撰写可能更像一个单纯的培训。事实上，这是最为敏感的阶段，从总体上决定着项目的未来速度及其成功前景。这个阶段会生发具象而深刻的变化，其对于如何编制和后续如何使用文档这一问题的关注丝毫不亚于对文档主题本身的关注。
在这期间，技术文档工程师将更加接近以任务为导向按主题撰写的标准方法。这些方法分为三个部分：适用于概念、指南和参考信息的文档模块（主题）。在引入全新编辑系统之前进行方法培训具有多重优势：对于编辑人员来说，分别学习方法和软件显然更加简单，因为这二者本身就意味着深刻变化。另外，他们几乎可以始终在当前环境（即使在传统的文字编辑中）中按主题撰写，并在引入新系统之前创建采用新结构的内容，以便日后更轻松地将其转移到新系统之中。为锁定新方法，除此前所确定的从指导方针（发挥动力作用）到信息模型之外，还应将流程和编辑指南作为标准加入其中。
选择适当的编辑系统
在项目末期，编辑系统是核心所在。它可能是一个“帮助创作系统 (Help Authoring System)”，比如 MadCap Flare、Author-it 或 RoboHelp，也可能是一个内容管理系统 (Content-Management-System)。系统选择取决于有关目标群体、流程、方法和标准的现有决策。此外，该系统应只要求稍微优化或调整信息模型、编辑模式和流程。 下一步则是用新系统完成内容迁移和文档首次交付。这个旨在让软件文档可持续适应未来的项目也将随之全部结束。
评论 (0)
无评论发表评论