为软件系统编写文档在软件开发中并不是什么新鲜事。几乎每个人都明白这个原则:
你的软件产品对用户来说有多优秀并不是最重要的,因为如果你的文档不够好,用户就不会使用它!即使在某些情况下用户不得不使用你的产品,他们也需要好的文档才能高效使用,否则可能会误用你的产品。
不幸的是,几乎没有正确组织技术文档的实践和方法论。在团队合作中,编写文档仍然面临挑战。
仓促开始和结束
编写技术文档的任务似乎总是优先级很低:它需要大量时间,而且没有立即的正面反馈!所以文档编写一再推迟,直到某个时候不得不完成,比如新团队成员加入项目或我的开源产品即将发布时。只有到那时我才惊恐地意识到我没有文档。文档最终被草草编写,以至于完成后完全被忽视。随着系统的发展,这些文档逐渐脱节并变成谎言!这种说法乍一看似乎很荒谬,但在我周围经常发生。
混乱的结构
就像编写代码一样,混乱的结构可能相当致命。我们可以使用类似 technical-writing-template 的东西来确保单篇文章的质量基于模板约定达到一定标准。然而,在复杂的软件系统中,高质量的单篇文章是不够的。许多优秀的软件产品都有适当结构化的文档,让初学者和长期用户都能轻松阅读。我认为文档无法摆脱混乱有几个原因:
- 文档由多人编写。《探索极限编程》描述了XP团队中"文档编写者"的角色。尽管如今敏捷实践盛行,但在敏捷团队中,无论是成熟的"角色即帽子"概念还是传统的"角色即职位"概念,"文档编写者"的角色可能很少见。文档由不同的人为不同的部分编写,然后组合在一起,自然会导致混乱。
- 缺乏对抗混乱的模式。与软件编写不同,我们有深入人心的默认约定作为架构风格。甚至还有C4模型来可视化软件架构,帮助团队保持一致理解,并允许架构有序演变。除了本文将介绍的文档象限外,未发现其他有影响力的写作模式。
两种组织方法
- 结构化文档
通过观察优秀技术文档的组织结构,如Unix手册、Spring Boot或React,你会发现它们都是结构化的。主要用法是根据索引浏览感兴趣的内容。
一般来说,编写技术文档基本上意味着编写类似的结构化文档。结构化文档不仅是目前最主流的文档组织方式,在可预见的未来也将如此。
保持清晰的结构绝非易事。作者很幸运地看到了一种确保正确生成结构化文档的模式:文档象限。
在坐标系中,将象限分为两个轴描述文档的属性。横轴描述文档的使用场景是倾向于工作还是学习,纵轴描述是倾向于理论还是实践。这四个象限分别是教程、操作指南、参考和解释:
图片
文档象限为其内容的呈现定义了明确的界限,使文档看起来简单易懂,更适合对外输出,并帮助用户快速入门。
- 图形化文档
除了结构化文档之外,似乎还有另一种组织文档的方式:基于图形,并且正在获得影响力。通常,为了保持文章的简洁性和连贯性,我喜欢使用链接文本指出其他地方的相关概念。一旦你深入几层链接,你会发现文档承载的知识很快形成一个大网络。"知识图谱"这个术语恰如其分。自2012年Google知识图谱发布以来,知识图谱的主要应用仍在搜索引擎和文献检索领域。像logseq这样的产品采取了不同的方法,通过加强知识之间的联系,以图形化方式组织文档。其主要用法涉及关键词搜索结合跳转到相关内容(链接引用)。
在使用 logseq 时,我发现这种方法更符合人类在大脑中构建知识模型的方式,有助于深入全面地理解问题。这与Luhmann的"Zettelkasten方法"产生共鸣。
我认为,基于图形的文档组织更适合作为团队的知识库,用于团队内部的知识生产和管理。这与其主要操作模式有关。虽然我认为关键词搜索是一种有效的方法,但它对新用户的搜索能力提出了挑战。
选择参考
当你开始构建文档时,即使没有任何考虑,你也应该使用一些文档工具或协作平台来保存你编写的文档。我了解一些常用的文档工具:
文档生成工具:
- sphinx
- docusaurus
文档托管和协作:
- Google Docs
- Confluence
图形化文档工具:
- logseq
这些文档构建方法和工具有什么用途?世界上可能没有完美的软件工具或系统能满足所有个性化需求。当你选择Google Docs进行协作编辑时,你将不得不处理大量样式调整。当你使用Logseq作为团队的内部知识库时,其独特的文档标记格式使得迁移到其他工具变得困难。这令人沮丧!因此,构建文档也需要类似的技术决策工作来确定适合的解决方案。这意味着在困难的权衡中做出选择,选择一个满足要求的解决方案,其优点仍然鼓舞人心,而缺点是可以容忍的。
值得注意的是,具备编写文档的能力并不是唯一要求;在选择解决方案时,我们似乎更重视功能之外的重要特性。是的,文档构建也应该满足可预见的非功能性需求:
- 可移植性:在可预见的未来,是否需要将文档迁移到另一个环境?
- 可用性:用户体验和易用性、协作能力、国际化。
- 合规性
- 可访问性:仅在内部网络有效?完全公开还是需要授权和认证?
- 存档:文档如何更改、保存和备份?
- ...
令人兴奋的文档构建解决方案
- sphinx + Document Zenith + Git
使用Document Zenith组织内容,保存在Github等托管平台上,并使用Sphinx生成电子书进行发布,或生成HTML进行私有部署。
优点:
- 良好的国际化支持
- 高度灵活性
- Sphinx高度可配置,生态系统成熟
- 文档托管和私有部署有多种替代选择
- 只依赖Python运行环境,可移植性高,可以随软件版本迭代更新、维护、部署,并纳入迭代管理
缺点:
- 文档贡献者需要熟悉两种技术:Git和markdown
- logseq
使用logseq作为知识库,并将文档保存在Github等托管平台上。
优点:
- 可以以极低成本构建知识图谱,作为知识库
- 使用方式涉及关键词搜索和跳转到相关内容,这种交互方式更容易让人专注于思考
缺点:
- 使用方式涉及关键词搜索和跳转到相关内容,不适合初学者快速入门
- 需要每个用户安装Logseq客户端
- 贡献者需要熟悉两种技术:Git和markdown
- 难以对外发布内容
- Google Docs/Confluence + 文档管理
优点:
- 多用户协作
- 内置认证和授权支持单点登录(SSO)
- 流行产品,易用性好
缺点:
- 需要手动管理存档和备份,容易导致混乱
- 可移植性差
