经验分享 | 对用户文档进行伤筋动骨式的重构是怎样一种体验？

Foreword

转眼间，2019 年的一半已悄悄溜走，是不是好多想做的事情还没来得及做呢？今年上半年，我所在的文档团队除了完成大量的文档更新外，还与前端小伙伴合作完成了一件对用户文档来说“伤筋动骨”式的大事情：重构文档，并实现多版本展示。

对于从事技术写作的 Technical Writer（技术文档工程师）来说，能参与一个产品用户文档的重构也是一件蛮难得的体验，因为并不是在每个公司都有这样的机会。如果你所服务的产品文档本身就很完善了，那么即便调整也多半不会动整体结构，多是小修小改，或者只是文档内容的增删修改，当然也许会探索新的文档呈现方式。

实际参与下来，发现这是一次难得又“痛苦”的体验。接下来跟大家详细聊聊，本文结构如下：

• 什么是文档重构和多版本
• 为什么说“伤筋动骨”
• 为什么要做文档重构和多版本
• 时间周期、参与人员与执行过程
• 重构文档需注意哪些问题
• 实现文档多版本需注意哪些问题
• Technical Writer 的主观体验

说明：本文分享的是 TiDB 的文档重构与多版本展示的实现。TiDB 是 PingCAP 公司在做的一款开源分布式 NewSQL 数据库，PingCAP 是我现在就职的公司。

什么是文档重构和多版本

或许有些小伙伴仍感到困惑，那就先跟大家说说这件事情到底是啥。

什么是文档重构

本文中的文档重构指的是对完整的中、英文用户文档按照 DITA 理念进行文档结构的重新组织，以及文档内容的拆分重组。内容的拆分重组会涉及文档文件与具体文档内容的增、删、完善。

对技术写作有所了解的小伙伴一定对 DITA 不陌生了，它指的是 Darwin Information Typing Architecture。其核心就是将内容分为典型的三类：Concept，Task，Reference。

之前在书单分享中提到过一本 IBM 出的专门讲 DITA 的书 DITA Best Practices，想加深了解的小伙伴可以去看看。

什么是文档多版本

本文中的文档多版本指的是在公司中、英官网的文档页面支持显示不同版本的文档，用户可以选择看某一个版本的文档。该版本对应的是产品的大版本，如 v3.0。这样做是为了让使用某一个版本的用户可以查看对应的文档。

文档重构与多版本的范围

• 重构的范围：TiDB 的全部中、英文用户文档。
• 多版本的范围：TiDB 2.1、3.0、dev（最新开发版）三个版本的全部中、英文用户文档。

为什么说“伤筋动骨”

因为改动特别大，简单列举四点：

• 文档目录与原来相比，几乎全部进行了调整。

• 对绝大多数文档进行了重命名，文档链接与原来相比，已完全不同。

• 对原来放置位置或者组织欠妥的内容进行了拆分重组，文档内容与原来相比，一些位置与内容都发生了变化。

• 所有重构工作均同时针对中文文档和英文文档，要保证二者结构更新的一致性、中英切换的正常跳转。

为什么要做文档重构和多版本

是啊，既然如此伤筋动骨，那为什么还要做呢？只做日常的文档更新不行吗？

这是因为当前文档需要优化，需要提高使用体验，经历一些“痛苦”是必须的。假如现在不做，在产品快速成长的情况下，文档会越来越多，到时候想做很可能会更“痛苦”。

如此看来，在日常中英文档更新频繁的情况下，对文档进行重构是一件痛并快乐的事情。

时间周期、参与人员与执行过程

• 时间周期：3 月下旬 ~ 6 月下旬。

  需要说明的是，这段时间并不是全部用来做文档重构和多版本，这件事只是工作的一部分。日常工作还有很多各种各样你可能想不到的事情，尤其是对于 Technical Writer 来说。

• 参与人员：2 个文档同学 + 1 个产品与社区经理 + 1 个前端同学。

  这里的参与人员指的是具体执行的小伙伴。前三个人主要负责内容，前端同学负责官网的实现，以及期间遇到的各种问题的支持解决。其中，产品与社区经理在加拿大，有十几个小时的时差。

• 执行过程：这里简单分享下总体的流程。

  先做文档重构，再做文档多版本，多版本必须在文档重构之后，以便于采用新的结构。在文档重构方面，英文文档先于中文文档，这与负责内容的小伙伴们当时手头工作相关。中文文档在结构、文件名上与英文版保持严格的一致（便于之后维护），但允许中英文档存在差异，因为受众不一样。

  文档重构需要花费的时间较长，从结构的确定、执行，到测试、上线。在重构期间，不能影响官网中、英文档的正常使用，还要支持收藏了原链接的用户可正常访问文档。6 月中旬时，文档重构基本完成，下旬时，文档多版本也顺利实现。在之后接下来的一段时间，还需要对文档结构和内容进行一些打磨和相关的更新。

重构文档需注意哪些问题

对文档进行重构是一件比较复杂的事情，至少要注意或考虑以下几点：

• 重构要谨慎，不要随意重构文档。

  重构前需要讨论确定是否确实有该需求，需要决策者达成一致。否则，会浪费大量的时间和人力成本。

• 重构较复杂，不只是改一下结构。

  重构不只是调整下文档目录，而是整个用户文档的重新布局。重构工作会涉及：目录结构的重新组织，文档放置位置的调整，某一块文档内容的重组，优化所需的内容更新与补充，文件的重命名与路径更新，新路径引发的链接更新，对原文档链接的访问支持，等等。

• 重构要测试，不能影响文档的正常使用。

  重构过程中，对于不能 100% 确定不影响线上文档的改动，需要进行测试。测试没有问题后，再将更改推到线上。另外，如果有用户收藏了重构之前的文档链接，可能还有必要让新文档支持旧版链接，以保证收藏了原链接的用户可以正常访问文档。

• 重构较耗时，需留出足够的时间。

  在重构过程中，可能会遇到各种各样的问题，有些是在最开始设想时不会想到的事项，要留出处理这些事项的时间。有时一次需要同时改动十几个、几十个、甚至上百个文件。对于这样的改动，Review 的过程也会占用较长的时间，而 Review 又必须尽可能地细致。一个小的疏忽，一个多余的字符，一个漏掉的字符，都可能导致某个文档不可用，甚至引起构建失败。

• 参与重构的各方沟通要明确及时。

  重构不是一个人完成的，涉及多个小伙伴的合作。对于那些需要对方了解的事项，一定要及时告知，并确认对方已收到。例如，重构过程中，你发现之前已推到线上的改动仍有一些之前未测试出来的问题，此时由谁去修复呢？如果另一个小伙伴也在差不多的时间发现了，可能也会去修复。此时，最好让所有参与者都知道这个问题，知道谁在跟进修复，以避免俩人同时去做一件重复的事情，浪费时间和人力资源。

实现文档多版本需注意哪些问题

在此次重构文档之前，虽然在 GitHub 的文档 repository 中也有不同版本的文档，但是并未在官网展示和维护，只在官网维护了最新版本的文档，对应产品的最新版。这次重构之后，需要在官网展示三个版本的文档，即：TiDB 2.1、3.0、dev（最新开发版）。

要实现文档多版本的展示，文档团队要做的很重要的一项工作就是：根据前端同学的要求准备好各版本的内容。因为在重构文档阶段就已将多版本的实现纳入考虑，很多事项在处理时也考虑到了便于之后多版本的实现，所以多版本的实现还是蛮快的，主要是前端同学的辛劳。

此次实现多版本，在内容方面主要考虑的问题如下：

• 链接规则的变更。

  各版本文档正文包含的链接是否能正常跳转，选用哪种链接规则最利于今后的维护等。要实现多版本展示，官网的内容读取规则也要变更，该变更也可能会影响文档目录 TOC 文件中的链接规则，同样也会影响所有图片的链接规则。我们要做的就是根据与前端同学确认的新版链接规则进行批量处理。

• 文档别名的处理。

  因为在文档重构阶段，为了确保旧链接依然有效，官网展示的文档（即最新 dev 版）都加了 aliases 别名。而多版本实现之后，官网默认显示的版本为 v3.0 版本，也是希望保留了旧链接的用户关注的版本。

  此时，要做的一项工作就是去掉 dev 版本中的全部 aliases，只保留 v3.0 版本中的 aliases。这样做是因为，如果某个旧链接既可以跳转到 dev 版本，也可以跳转到 v3.0 版本，那么在选择跳到哪一个时可能会引起一些错误或构建失败。在批量删除 v3.0 版本中的 aliases 时，无限感慨正则表达式真是太有用了！

• 版本与文档内容的一致。

  各版本的文档需与产品的版本一一对应。在多版本实现过程中，新的文档不断增加，而且还有大量原文档的更新，在实际处理中，需要做的是将属于某个版本的加进去，将不属于某个版本的删除或更新为对应的内容。在多版本上线之后，通过更新 GitHub repository 的 Pull Request 模板，提醒小伙伴们注意多版本的更新，并给 PR 添加 label 来标示所影响的版本。

• 各版本文档 PDF 的下载。

  因为部分用户有下载 PDF 版本文档的需求，在实现多版本后，前端同学帮助实现了对各版本 PDF 的下载支持。

Technical Writer 的主观体验

正如开头所说的，从个人的主观感受来说，这是一次难得又“痛苦”的体验，痛并快乐着。从对这件事的主观评价来说，它是一件很复杂的事情。从这件事对 Technical Writer 的要求来看，它需要思虑周全与细心再细心。

在文档重构和多版本上线后，我与一起参与的同事聊过对于此事的感受，都觉得复杂，哈哈~

这都是我们第一次对产品文档进行重构。回头看，自觉并没有走什么弯路，但确实有不少意料之外的事项，以及由此带来的很大的工作量。如果有机会再来一次，对可能遇到的问题和工作量应该会有更好的把控了。

此外，另一个特别深的感触是，做这个事情尤其需要思虑周全与细心，因为任何一点疏漏都有可能导致构建失败。或许你觉得自己特别细心，但当你处理或者 Review 几十上百个文件时，你是有可能会有疏漏的。

有时，处理某一块文档，几十个文件，除了重命名、换目录、改 TOC、加 aliases 之外，还要全局搜索是否有其它文档引用了该文档，尤其是引用正文某个二级或三级标题的那种，要保证更新后依然可以跳转到正确的位置，就必须更新引用链接里的文件名。这个复杂的过程需要在要做哪些事项上思虑周全，在实际做的过程中尽可能细心。

Afterword

想看重构与多版本效果的小伙伴可以打开以下链接：

• TiDB 中文文档官网：https://pingcap.com/docs-cn/v3.0
• TiDB 英文文档官网：https://pingcap.com/docs/v3.0

截图于 2019 年 6 月 30 日

想了解重构细节的小伙伴可以去 GitHub 上看中、英文档各自的 repository，里面是所有官网文档的源文件，有具体的修改记录（可在 Pull Requests 中筛选加了 "refactor" label 的 Pull Request）：

• TiDB 中文文档 repository：https://github.com/pingcap/docs-cn
• TiDB 英文文档 repository：https://github.com/pingcap/docs

想加入这个团队一起来体验各种挑战的 Technical Writer 或 Content Strategist，可以扫描下方二维码了解招聘信息或者直接发简历至 lilin@pingcap.com 哦~

你可能想读：

技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
GitHub + Markdown 的新轻型技术写作模式速览
GitHub + Markdown 的技术文档方案深度解析
Technical Writer 日常工作中好用的小工具
技术传播人士应该知道的色彩搭配常识
如何使用颜色来提高技术文档的可读性？
Technical Writer 如何 Review 技术文档？| 重细节+全局观
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
优质免费资源推荐 | 9 期技术写作短视频教程带你从入门到进阶
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
Technical Writer 想参与开源项目为文档做贡献，需提前掌握哪些知识？
Technical Writer 如何参与开源项目的文档，以不断提升专业技能?
技术传播沙龙精彩分享 | 高校老师与行业大牛谈“互联网技术写作”
英语技术文档的标题到底该大写还是小写？
不同阶段如何应对 Technical Writer 的职业顾虑或烦恼？
如何使用正则表达式批量添加和删除字符？
英语技术文档中如何正确使用时态？
英语技术文档中如何正确使用人称？
英语技术文档中如何正确使用无序列表和有序列表？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
Technical Writer 需要 Technical 到会写代码吗？
如何利用 GitHub Pages 和 Hugo 轻松搭建个人博客？
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记

-END-