写作工具迁移案例（一）

分享一个曾参与的工具迁移案例。技术写作团队为主导角色，“有的放矢”，精心计划、准备，按部就班实施计划，完成迁移，取得成效，享受“登顶”的愉快。

公司背景及产品文档情况

金融科技公司，风险评估及信用管理解决方案提供商，全球在欧洲、北美及亚太地区设立研发中心。每个研发中心设立了全方位角色团队：项目管理、架构、开发、测试、产品、UX设计师、技术写作，等等。

本案例中的产品是亚太研发中心下的产品，该产品包含了多个相对独立的附属产品。产品文档包包括与产品本身及其附属产品相关的文档，主要包括两大类：用户文档及开发文档。下面的表格列出了维护文档的角色以及使用的写作工具。

文档分类	文档类型	内容开发角色		写作工具
用户文档	– 使用指南、安装及配置指南 – 在线帮助	技术写作		非结构化 Adobe FrameMaker Adobe RoboHelp
	发布说明	产品		Microsoft Word
开发文档	测试报告、开发者手册、数据库模型图	开发、测试		Microsoft Word

问题及改进目标

基于现有文档开发及输出过程中的问题，为了优化文档发布平台及机制，确定如下改进目标。

现有问题	改进目标
FrameMaker到RoboHelp同源输出HTML过程中，出现大量的失效超链接，手动修复的工作量过大。	新工具需要能够解决断链问题。
FrameMaker维护的文档，一旦模板更新，所有文档需重新套用模板，耗费一定的工作量。	新工具需要支持内容与样式分离，以释放技术写作团队的工作容量，更专注于开发文档内容、提升文档质量。
开发文档，只能单人编辑；文档存放在代码开发使用的存储工具，查看及获取有限制；邮件传递，出现版本不一致的问题。	新工具需要支持在线查看、多人协同编辑及版本管理。
文档输出为PDF后发布在客户支持门户网站，内部、外部用户只能下载整个文档后查阅，无法在下载前确定文档是所需文档。用户的反馈只能通过客户支持部门或销售部门进行传递到技术写作团队，过程周折，难以跟踪。	新门户网站需要支持在线查看文档页面、下载单个页面及整个文档、在线反馈，便于内外部的双向交流。

准备工作

由于涉及全球三个研发中心下的所有产品文档，技术写作团队迁移前进行了充足准备，组建两个工作小组，分别跟进协同编辑工具及结构化写作工具。三个区域的技术写作团队挑选成员作为代表，负责与工作小组沟通、学习，向本地团队传达迁移项目的进度实施计划，协助本地团队完成迁移工作。

两个工作小组的职责包括：

• 协同IT部门调研并确定工具。
  • FrameMaker维护的文档切换到基于DITA的结构化写作工具，支持多格式输出。
  • Microsoft Word维护的文档切换到Confluence协同编辑工具。
• 制定工具使用规范，并形成文字说明。
• 调研迁移现有内容到新工具的方式（人工或自动化批量迁移）。
• 调研控制样式表的Plug-in工具，保证文档的出版风格一致。
• 培训三个地区的技术写作团队使用新工具。
• 对使用新工具过程中提出的问题提供反馈、答疑。

同时，工作小组与DevOps团队协作，搭建持续集成环境，单个文档的构建任务定时在指定路径获取最新内容，输出文档并存放指定路径。

公司采用 Salesforce.com CRM平台，文档发布门户网站与客户支持门户网站无缝结合。支持在线查看、在线反馈、下载单个页面及整个文档，反馈将直接送达技术写作团队并跟踪处理。

内容迁移

对于将存量文档内容从FrameMaker迁移到Oxygen XML Author，可以采用人工方式或自动化批量方式，这取决于存量内容的多少及迁移者的偏好。对于新文档，建议在oXygen XML Author中直接创建。

• 人工方式即Copy+Paste，适合那些存量内容少的文档。
• 对于页数多的文档，我们可以使用Omni System开发的Mif2Go批量转换。虽然转换速度快，但转换前需要做准备（例如：在本地电脑上配置转换环境；在FrameMaker文档中说明步骤部分添加标记，以便工具识别并转换为Task类型主题），转换后也需要“清扫”自动化工具无法处理的标签。

从Microsoft Word到Confluence的迁移过程相对简单些。直接将文档导入Confluence，可以选择将Word文档按标题拆分到多个Wiki页面中，Confluence的导航栏中的树状结构体现文档目录。使用Confluence的插件Scroll Versions对文档进行版本控制，以及Scroll Exporters输出PDF及静态HTML页面并控制输出样式。

迁移成效

经过一年多的准备，技术写作团队及其他兄弟团队逐步开始往新工具迁移。

技术写作团队使用oXygen XML Author开发新的文档及迁移现有文档内容。原有的失效链接问题得到解决。内容与样式分离，释放技术团队工作量，更专注于开发内容、提升质量。CI环境定时构建最新版本文档，并应用配置好样式表输出文档。发布版本输出后直接推送文档门户网站。技术团队不但解决了已有的文档问题，提升区域之间的沟通与协作，收获新技能。

Conflunce打通了不同团队及个人之间的信息孤岛，形成协同工作环境，团队成员之间共享信息、文档协作、集体讨论、信息推送。富文本编辑器界面直观、简单易用，团队迅速上手。页面模板确保同类文档结构的一致性。查看及比较历史版本方便，按需恢复历史版本。通知机制向团队成员发送最新变化的通知。工具得到团队成员的青睐。

通过样式表及样式插件，两种工具维护的文档保持了一致的出版风格。新的门户网站解决已有问题，大大提升了客户满意度。

结束语

变更写作工具要实现预期目标，需要梳理现有问题，确定预期目标，充分调研，制定计划并实施。

相关阅读：选择内容开发工具