文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

我们一起聊聊如何编写技术文档

2024-11-29 19:07

关注

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

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

仓促开始和结束

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

混乱的结构

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

  1. 文档由多人编写。《探索极限编程》描述了XP团队中"文档编写者"的角色。尽管如今敏捷实践盛行,但在敏捷团队中,无论是成熟的"角色即帽子"概念还是传统的"角色即职位"概念,"文档编写者"的角色可能很少见。文档由不同的人为不同的部分编写,然后组合在一起,自然会导致混乱。
  2. 缺乏对抗混乱的模式。与软件编写不同,我们有深入人心的默认约定作为架构风格。甚至还有C4模型来可视化软件架构,帮助团队保持一致理解,并允许架构有序演变。除了本文将介绍的文档象限外,未发现其他有影响力的写作模式。

两种组织方法

  1. 结构化文档

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

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

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

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

图片

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

  1. 图形化文档

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

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

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

选择参考

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

文档生成工具:

文档托管和协作:

图形化文档工具:

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

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

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

  1. sphinx + Document Zenith + Git

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

优点:

缺点:

  1. logseq

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

优点:

缺点:

  1. Google Docs/Confluence + 文档管理

优点:

缺点:

来源:大迁世界内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯