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

2019-07-02 本文已影响0人 Lilian_Lee

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 之外，还要全局搜索是否有其它文档引用了该文档，尤其是引用正文某个二级或三级标题的那种，要保证更新后依然可以跳转到正确的位置，就必须更新引用链接里的文件名。这个复杂的过程需要在要做哪些事项上思虑周全，在实际做的过程中尽可能细心。