如何编写技术文档

为软件系统编写文档在软件开发中并不是什么新鲜事。几乎每个人都明白这个原则:

你的软件产品对用户来说有多优秀并不是最重要的,因为如果你的文档不够好,用户就不会使用它!即使在某些情况下用户不得不使用你的产品,他们也需要好的文档才能高效使用,否则可能会误用你的产品。

不幸的是,几乎没有正确组织技术文档的实践和方法论。在团队合作中,编写文档仍然面临挑战。

仓促开始和结束

编写技术文档的任务似乎总是优先级很低:它需要大量时间,而且没有立即的正面反馈!所以文档编写一再推迟,直到某个时候不得不完成,比如新团队成员加入项目或我的开源产品即将发布时。只有到那时我才惊恐地意识到我没有文档。文档最终被草草编写,以至于完成后完全被忽视。随着系统的发展,这些文档逐渐脱节并变成谎言!这种说法乍一看似乎很荒谬,但在我周围经常发生。

混乱的结构

就像编写代码一样,混乱的结构可能相当致命。我们可以使用类似 technical-writing-template 的东西来确保单篇文章的质量基于模板约定达到一定标准。然而,在复杂的软件系统中,高质量的单篇文章是不够的。许多优秀的软件产品都有适当结构化的文档,让初学者和长期用户都能轻松阅读。我认为文档无法摆脱混乱有几个原因:

1. 文档由多人编写。《探索极限编程》描述了XP团队中"文档编写者"的角色。尽管如今敏捷实践盛行,但在敏捷团队中,无论是成熟的"角色即帽子"概念还是传统的"角色即职位"概念,"文档编写者"的角色可能很少见。文档由不同的人为不同的部分编写,然后组合在一起,自然会导致混乱。

2. 缺乏对抗混乱的模式。与软件编写不同,我们有深入人心的默认约定作为架构风格。甚至还有C4模型来可视化软件架构,帮助团队保持一致理解,并允许架构有序演变。除了本文将介绍的文档象限外,未发现其他有影响力的写作模式。

两种组织方法

1. 结构化文档

通过观察优秀技术文档的组织结构,如Unix手册、Spring Boot或React,你会发现它们都是结构化的。主要用法是根据索引浏览感兴趣的内容。

一般来说,编写技术文档基本上意味着编写类似的结构化文档。结构化文档不仅是目前最主流的文档组织方式,在可预见的未来也将如此。

保持清晰的结构绝非易事。作者很幸运地看到了一种确保正确生成结构化文档的模式:文档象限。

在坐标系中,将象限分为两个轴描述文档的属性。横轴描述文档的使用场景是倾向于工作还是学习,纵轴描述是倾向于理论还是实践。这四个象限分别是教程、操作指南、参考和解释:

文档象限为其内容的呈现定义了明确的界限,使文档看起来简单易懂,更适合对外输出,并帮助用户快速入门。

1. 图形化文档

除了结构化文档之外,似乎还有另一种组织文档的方式:基于图形,并且正在获得影响力。通常,为了保持文章的简洁性和连贯性,我喜欢使用链接文本指出其他地方的相关概念。一旦你深入几层链接,你会发现文档承载的知识很快形成一个大网络。"知识图谱"这个术语恰如其分。自2012年Google知识图谱发布以来,知识图谱的主要应用仍在搜索引擎和文献检索领域。像logseq这样的产品采取了不同的方法,通过加强知识之间的联系,以图形化方式组织文档。其主要用法涉及关键词搜索结合跳转到相关内容(链接引用)。

在使用 logseq 时,我发现这种方法更符合人类在大脑中构建知识模型的方式,有助于深入全面地理解问题。这与Luhmann的"Zettelkasten方法"产生共鸣。

我认为,基于图形的文档组织更适合作为团队的知识库,用于团队内部的知识生产和管理。这与其主要操作模式有关。虽然我认为关键词搜索是一种有效的方法,但它对新用户的搜索能力提出了挑战。

选择参考

当你开始构建文档时,即使没有任何考虑,你也应该使用一些文档工具或协作平台来保存你编写的文档。我了解一些常用的文档工具:

文档生成工具:

• sphinx

• docusaurus

文档托管和协作:

• Google Docs

• Confluence

图形化文档工具:

• logseq

这些文档构建方法和工具有什么用途?世界上可能没有完美的软件工具或系统能满足所有个性化需求。当你选择Google Docs进行协作编辑时,你将不得不处理大量样式调整。当你使用Logseq作为团队的内部知识库时,其独特的文档标记格式使得迁移到其他工具变得困难。这令人沮丧!因此,构建文档也需要类似的技术决策工作来确定适合的解决方案。这意味着在困难的权衡中做出选择,选择一个满足要求的解决方案,其优点仍然鼓舞人心,而缺点是可以容忍的。

值得注意的是,具备编写文档的能力并不是唯一要求;在选择解决方案时,我们似乎更重视功能之外的重要特性。是的,文档构建也应该满足可预见的非功能性需求:

• 可移植性:在可预见的未来,是否需要将文档迁移到另一个环境?

• 可用性:用户体验和易用性、协作能力、国际化。

• 合规性

• 可访问性:仅在内部网络有效?完全公开还是需要授权和认证?

• 存档:文档如何更改、保存和备份?

• ...

令人兴奋的文档构建解决方案

1. sphinx + Document Zenith + Git

使用Document Zenith组织内容,保存在Github等托管平台上,并使用Sphinx生成电子书进行发布,或生成HTML进行私有部署。

优点:

• 良好的国际化支持

• 高度灵活性

• Sphinx高度可配置,生态系统成熟

• 文档托管和私有部署有多种替代选择

• 只依赖Python运行环境,可移植性高,可以随软件版本迭代更新、维护、部署,并纳入迭代管理

缺点:

• 文档贡献者需要熟悉两种技术:Git和markdown

1. logseq

使用logseq作为知识库,并将文档保存在Github等托管平台上。

优点:

• 可以以极低成本构建知识图谱,作为知识库

• 使用方式涉及关键词搜索和跳转到相关内容,这种交互方式更容易让人专注于思考

缺点:

• 使用方式涉及关键词搜索和跳转到相关内容,不适合初学者快速入门

• 需要每个用户安装Logseq客户端

• 贡献者需要熟悉两种技术:Git和markdown

• 难以对外发布内容

1. Google Docs/Confluence + 文档管理

优点:

• 多用户协作

• 内置认证和授权支持单点登录(SSO)

• 流行产品,易用性好

缺点:

• 需要手动管理存档和备份,容易导致混乱

• 可移植性差