如何编写技术文档？

news2024/11/19 8:22:24

软件开发中，为你的软件系统编写文档并不是一件新鲜的事情。几乎所有人都明白这样的道理：

你的软件产品如何优秀对用户来说并不是最重要的，因为你的文档如果不够优秀，用户不会使用它！即便用户在某些情况下不得不使用你的产品，没有好的文档，用户无法高效使用或者以错误的方式使用你的产品。

不幸的是，鲜少能见到关于如何正确组织技术文档的实践及方法论。团队工作中，编写文档仍面临挑战。

仓促地开始和结束

编写技术文档这个任务看起来总是：优先级不够高，特别花时间并且没有立竿见影的正反馈！于是文档编写被一推再推，直至在某些时刻不得不做，比如新人要上项目了，我的开源产品要发布了，才震惊地发现我竟没有文档。文档最后被随意编写，以至于完成后就被彻底忽视。随着系统的演进，这些文档慢慢脱节，变成谎言！这个论断乍一看如此地荒谬，可是却在我身边常常发生。

混乱的结构

如同代码编写一样，混乱的结构是相当致命的。我们能使用类似于technical-writing-template这样，基于模板约定的方式使得单篇文章的质量达到一定的水准。然而在复杂的软件系统中，高质量的单篇显然是杯水车薪的。事实上，众多优秀的软件产品它们基本都具备恰到好处的文档，清晰的结构使得初学者和长期用户读起来都毫不费力。我以为，未能使文档免于混乱的原因有以下几点：

文档是由多个人编写的。《解析极限编程》中描述一个XP团队中会有“文档撰写员”的角色。即便敏捷实践大行其道的今天，敏捷团队中，不论是成熟的“角色是帽子”，还是传统的“角色是岗位”，都大概很少会见到“文档撰写员”这一角色。文档是由不同的人编写不同的部分，再组合而成的，混乱是自然而然的结果。
缺少对抗混乱的模式。不同于软件编写，我们有架构风格这样深入人心的默认约定。甚至有C4 model来可视化软件架构，帮助团队保持一致的认知，并使架构有序地演进。文档的编写除了本文将要介绍的文档象限之外，并未发现任何一种有较大影响力的编写模式。

两种组织方式

结构化文档

通过观察优秀技术文档的组织形式，诸如unix manual、Spring boot或者React，你会发现它们都是结构化的。主要使用方式是按照索引查阅感兴趣的内容。

通常，所谓编写技术文档，基本意味着编写类似的结构化文档。结构化文档不仅仅是当前最为主流的文档组织方式，在可预见的未来也会如此。

保持清晰的结构绝非易事，笔者深感幸运能够看到一种确保正确生成结构化文档的模式：文档象限。

在一个坐标系下，划分象限的两条轴描述了文档所具有的属性，横轴描述文档的使用场景是偏于工作的还是偏于学习的，纵轴描述文档是偏于理论的还是偏于实践的。这四个象限分别是tutorials，how-to guides，reference和explanation：

	Tutorials	How-to guides	Reference	Explanation
面向	学习	特定目标	信息	理解
必须	能够让新手从0开始	演示如何解决一个特定的问题	描述你的作品	解释原理
形如	一个课程	一系列步骤	枯燥地描述	描述性的解释说明
类似于	教一个小孩子如何做饭	一本烹饪书籍上的一条食谱	百科全书的参考文章	一篇关于烹饪社会史的文章

文档象限将其内容呈现方式划定了明确的边界，让文档看起来简单明了，更适合对外输出，帮助用户快速上手。

图谱化文档

结构化文档之外似乎还存在另一种文档组织方式：图谱化，并且初具影响力。很多时候，为了保持文章的简洁和内聚，我喜欢使用链接文字将一个相关概念指向别处。一旦顺着链接深入几层，就会发现文档所承载的知识很快组成一张大网。知识图谱一词简直恰如其分。自2012年谷歌知识图谱发布以来，知识图谱的主要用武之地仍在搜索引擎，文献检索领域。有诸如logseq这样的产品另辟蹊径，强化知识之间的链接，以图谱化的方式组织文档。其主要使用方式是关键字检索加上相关内容（linked reference）的跳转。

在使用logseq的过程中，我发现这种方式更契合人类在大脑中构建的知识模型，有利于深刻又全面地理解问题。这与卢曼的《卡片笔记写作法》有异曲同工之妙。

笔者以为，图谱化的文档组织方式在团队中更适合知识的生产和管理，即作为团队的知识库。原因与其主要使用方式有关。尽管我认为关键字检索不失为一种高效的方式，但是给新用户的检索能力提出了挑战。

选型参考

当你开始着手构建文档的时候，即便不作任何考量，也要借助一些文档工具甚至协作平台来保存你编写的文档。笔者了解到一些常用的文档工具：

文档生成工具：

sphinx
docusaurus

文档托管与协同：

google doc
confluence

图谱化文档工具：

logseq

了解到这些文档构建方式和工具有什么用呢？这个世界大概不存在一个完美的软件工具或者系统使得所有的个性化需求都被满足。当你为了协同编辑选择了google doc，将不得不面对大量的样式调整工作。当你使用logseq作为团队内部的知识库，其特有的文档标记格式使其难以迁移到其他的工具里。这真让人沮丧！于是乎，构建文档也要进行类似技术选型的工作，确定一个合适的方案。这意味着要在艰难的权衡之下，选择能满足需求的方案，其优点仍令人振奋，其缺点还可以忍受。

值得注意的是，具备能写文档这样的功能并非唯一的需求，选择方案时我们似乎更看重功能以外的重要特性。没错，文档构建也该满足可预见的非功能性需求：

可移植性：在可预见的未来，是否需要将文档迁移到另一个环境？
可用性：用户体验与易用性，协作能力，国际化
合规性
可访问性：仅内部网络有效？完全公开还是要通过授权鉴权？
存档：文档如何被变更，保存，备份？
…

令人激动的文档构建方案

sphinx + 文档象限 + Git

利用文档象限组织内容，利用Github等托管平台保存，sphinx将其生成为电子书发布，或者生成HTML进行私有化部署。

优点
- 良好的国际化支持
- 极高的灵活性
- sphinx高度可配置，拥有成熟的生态
- 文档托管及私有化部署具有众多的代替选项
- 只依赖Python运行环境，具有极高的可移植性，可以随软件版本迭代一起更新，维护，部署，纳入迭代管理
缺点
- 要求文档的贡献者熟悉两种技术：Git 和 markdown

📝 Note: 这里有一个How-to guide: 于sphinx上实践文档象限

logseq

使用loqseq作为知识库，利用Github等托管平台保存文档

优点
- 能够以极低的成本构建知识图谱，作为知识库
- 使用方式是关键字检索和关联内容跳转，这是一种让人更容易聚焦于思考的交互方式
缺点
- 使用方式是关键字检索和关联内容跳转，并不适合新手快速上手
- 需要每一个用户安装logseq的客户端
- 要求文档的贡献者熟悉两种技术：Git 和 markdown
- 难以对外发布内容