使用代码开发工具及流程管理产品文档

Posted 2021-04-25 中国技术传播

Sport is not just the game I play. Sport is who I am, what I am, why I am. It’s every second on the clock, every moment I live – gameday or any day.

—— adidas

在 tcworld 中国2018大会上，我做了《软件和文档同步开发》的发言。发言题目的选择，结合在软件行业编写文档的从业经验、对软件文档的编写工具和开发流程的思考，结合参与的文档内容管理平台项目过程中接触到国内外业界同行的实践，选择了互联网企业、软件产品企业可以借助代码开发工具及流程来开发文档的主题。

曾经在软件行业做了7年的文档，当时，软件开发使用的是敏捷开发模式，文档团队也采用敏捷的方式来开发文档。

• 工程团队中所有角色，包括产品经理、项目经理、开发、测试、文档，安排在敞开式的办公区，方便团队的沟通、讨论。

• 工程团队按模块或产品功能分为几个小组，每个小组专注于一、两个产品模块。文档团队也分配到不同的开发小组中，每个文档人跟进一两个开发小组。文档团队参与开发团队的会议，包括发布计划会、迭代开发功能演示会、站会，以及其他与产品开发相关的会议。这些会议帮助文档团队了解产品功能和开发进度。

• 文档开发流程上是按迭代来更新文档，文档组基于前一迭代开发的功能来更新文档，并将更新的内容发给相关的开发、测试、产品工程师进行审阅，在开发期结束时，将当前发布期内的文档进行统稿，由开发团队进行最后一次审阅，以及技术编辑进行语言审校。

  
  

文档开发看起来似乎是和产品开发并行的，仔细分析，文档的开发流程中还是有可以改进的方面。

首先，从时间表上看，同时几个产品发布并行或有重叠的时间段。文档的发布跟随产品，文档组同时服务于并行的产品发布，在发布中期和靠近发布结束时真正开始更新文档，文档交付完全是为了产品交付，文档的完整性、准确性和可用性存在风险。

其次，文档团队是文档的负责人和主要内容贡献者。文档团队不是技术专业人员，自身的背景和对产品认识有限，文档内容从深度上未能达到专业的层次。另一方面，软件和互联网产品资料的读者包括了在企业中负责安装和维护系统的终端用户与管理员，他们希望能从产品资料中获取专门化、深层次的信息。

第三，使用专门化的的写作工具维护文档，会限制内容贡献的来源。除了文档团队，其他角色的工程师无法获取源文档编写和修改内容。文档发出审阅后，一般是将反馈和改进意见以评论的形式添加到PDF文档中，由文档团队收集、汇总，应用到文档中。

第四，当时的产品包包括了大概50左右个大大小小的文档，有的是使用Microsoft Word来维护，有的用Adobe FrameMaker。一旦公司的文档模板修改，文档团队需要确保在发布前，对所有的文档套用最新的模板格式，可以想象，格式化工作需要耗费相当一部分时间和精力。这个痛点存在普片性，很多企业的文档团队都对此感到头疼。

第五，缺乏评审机制。文档更新后，通常输出PDF版本，经邮件发送到相关审阅人员，没有评审机制能够跟踪审阅任务是否按时完成。没有反馈和反馈延迟是常态。另一方面，由于缺乏评审机制的支持，一些来自“一线”人员的反馈，例如客户支持、销售、以及实际产品使用者，他们对文档的反馈需要经过“漫漫长路”才能传递到文档团队。

第六，通知系统或跟踪系统的缺乏在一定程度上影响评审文档的兴趣。文档团队将反馈及改进意见应用到文档中，但缺乏一个通知系统或跟踪系统，反馈者无法了解每一个反馈都应用到文档中了，无法了解他们的反馈得到了重视并促进了文档质量的提升。在某种程度上影响了评审文档的兴趣。

第七，缺乏文档持续集成环境，文档的获取途径有限。2016年以前，文档团队是没有持续集成的环境，最新的文档版本是文档团队按需输出，通过电邮或共享文件夹进行传递。直到2016年，建立了持续集成环境，定时将最新的文档内容输出PDF及html格式的文档，但文档成品的获取也仅限于文档团队，未对其他角色的工程师开放。

第八，上面有提到，文档团队的工作有一部分是确保交付的文档使用最新的文档模板。百分之二十左右的时间用于格式化文档。如果是迁移新的写作工具，还需要预留额外的百分之二十的时间学习使用新工具以及迁移内容。这在一定程度上占用了文档团队用于改进内容质量的时间和精力。

概括文档开发和管理过程中的问题：

• 文档交付是为了产品交付。

• 文档开发未能与产品开发平行。

• 文档开发中有相当一部分的手工操作可以减少。

• 文档团队未能全身心专注于内容开发。

• 文档质量需要提高以达到用户要求。

  
  

因此，我们可以借用代码开发工具和流程，改进文档开发中的问题，以提升内容质量。

如何对文档进行代码化管理呢？其中包括：使用轻量级标记语言（例如Markdown，AsciiDoc，reStructuredText ）来记录产品信息；拓展内容的所有权，让研发、测试、产品工程师也成为内容的所有者，与文档团队一起，参与内容的贡献；使用静态生成器来预览文档；使用分布式版本控制系统保存内容源；持续集成和构建最新版本文档；支持将内容自动发布到网站。

文档代码化管理的好处在于：

• 提升文档开发的协同性。软件产品文档的读者与产品的开发人员有着类似的技术背景，当文档团队与开发人员协同开发文档时，意味着更靠近读者。代码开发系统中的贡献图表可以帮助我们了解哪些开发人员专注与哪些领域，以便让最专业的人才来撰写内容。此外，通过协同开发文档，文档团队与其他角色共同承担提升文档质量的目标。

• 提升文档内容质量。文档团队无法了解产品的全部信息，特别是复杂软件产品。仅有一部分开发人员对复杂产品有深度的了解，因此，我们需要鼓励这部分开发人员将深层次的技术细节添加到文档中。这些技术细节对软件文档的质量起着至关重要的作用，特别是那些面向开发人员的技术文档。通过代码化管理文档，将文档分成若干个部分，鼓励技术人员参与编写数量不多但技术含量高的内容。

• 通过代码评审机制，记录和跟踪文档中的问题，以便制定计划，持续改进。评审机制也为读者和评审人员提供了报告和跟踪文档问题的途径，描述有误和费解的地方，以及如何修复问题。

• 文档问题得到改进后，代码开发流程中的通知系统会通知问题发起人。评审人也可以查看修改并进行确认。这样，提升研发人员审阅文档和提供反馈意见的兴趣，从而对内容质量进行持续提升。

• 研发人员模仿本地生产环境，将产品代码持续集成和部署到本地环境。文档可以采用相同的方式集成持续更新的内容，内容贡献者更新内容后，由指定的人员审阅确认后并合并到文档源仓库中。此外，也可以借助开发工具对文档进行简单的检查（例如，多余的空格、拼写错误等）。借助持续构建工具确保正确地自动化构建、发布文档，以便内容贡献者可以专注于内容编写，不需要分心于文档的构建。

• 文档借助具成本效益的工具编写、存储、测试、构建文档。例如，使用GitHub、GitLab、Bitbucket来存储源文档。

  
  

很多软件和互联网公司对开发者文档和支持文档进行了转换，使用代码开发工具和流程来管理技术文档，例如：Google、Microsoft、Twitter、Balsamiq、Rackspace。

Margaret Eker在Rackspace博客 Transforming Developer and Support Documentation with Docs Like Code 中，以及Zach在Transforming your Documentation Process的小组讨论中分享了他们的实践经验。

Rackspace转换项目由三位文档人Anne Gentle、Margaret Eker、Zach Corleissen主导。整个过程，由始至终，是多方协同的过程，包括管理层、文档团队、产品团队、客服团队、开发团队、以及设计团队。

开发者文档和支持文档的维护之前直依赖于授权工具和专业支持团队，改进后，由文档团队和开发团队协作维护，改进包括：

• 使用纯文本格式和代码系统交付文档。

• 文档的内容转为全员共创，包括项目中各个角色以及使用产品的外部用户。

• 使用版本控制服务来存储内容源。

• 使用持续集成和持续部署系统，以便自动化将内容在网站发布。

• 内容构建和部署时间缩短至一分钟之内。

• 通过基于浏览器的在线预发布环境，减少离线评审过程。

  
  

转换项目历经两年完成。规划项目时，统一、明确目标，即：为用户提供一个权威的自助内容来源。在项目执行中，发挥协同的作用。由项目各方一起开发平台及用户界面设计。

同时，变革各方发挥专长，专注于不同领域。文档团队专注于制定迁移计划，迁移文档内容，制定内容贡献的指导原则，统一写作指导原则和发布要求，制定内容模板，等等；开发、设计团队负责指导内容贡献者；管理层加强合作团队之间的伙伴关系。

这不仅仅是文档自身的变革，更多的是工作理念上、文化上的变革。对参与项目的各方提出了新的挑战。文档团队、客服团队需要学习代码开发工具和工作流。文档内容的贡献者转向多方，产品团队、客服团队参与编写、评审文档的工作。开发团队、设计团队需要指导其他角色的工程师使用开发工具和开发工作流贡献内容。

Rackspace对开发者文档、支持文档的变革，并非一蹴而就，从一开始对放弃现有的成熟编写工具的怀疑，到建立信任，建立合作团队，开发新平台，到跨地理区域的文档团队协同工作，以及寻求迁移文档的解决方案，期间客服重重困难和挑战。

总结一下，文档内容开发的模式多样化，除了 XML + CMS的模式，对于软件产品、互联网文档，特别是面向开发者的文档，我们也可以使用文档代码化的模式进行开发和管理。

参考资料

[1] Anne Gentle: Docs Like Code

[2] Margaret Eker: Transforming Developer and Support Documentation with Docs Like Code

[3] Video recording: Transforming your Documentation Process

[4] Andrew Etter: Modern Technical Writing

[5] Rackspace Contributor Guidelines

[6] The Write the Docs community: http://www.writethedocs.org/

（本文完）

2018

中国技术传播论坛

新时代 · 新技术 · 新发展

9月13-14日   杭州

目前代表中国该领域最高级别的行业年会活动，

欢迎大家参加本届论坛！

点击阅读原文，查阅主题及嘉宾预览