为软件系统编写文档在软件开发中并不是什么新鲜事。几乎每个人都明白这个原则:
你的软件产品对用户来说有多优秀并不是最重要的,因为如果你的文档不够好,用户就不会使用它!即使在某些情况下用户不得不使用你的产品,他们也需要好的文档才能高效使用,否则可能会误用你的产品。
不幸的是,几乎没有正确组织技术文档的实践和方法论。在团队合作中,编写文档仍然面临挑战。
编写技术文档的任务似乎总是优先级很低:它需要大量时间,而且没有立即的正面反馈!所以文档编写一再推迟,直到某个时候不得不完成,比如新团队成员加入项目或我的开源产品即将发布时。只有到那时我才惊恐地意识到我没有文档。文档最终被草草编写,以至于完成后完全被忽视。随着系统的发展,这些文档逐渐脱节并变成谎言!这种说法乍一看似乎很荒谬,但在我周围经常发生。
就像编写代码一样,混乱的结构可能相当致命。我们可以使用类似 technical-writing-template 的东西来确保单篇文章的质量基于模板约定达到一定标准。然而,在复杂的软件系统中,高质量的单篇文章是不够的。许多优秀的软件产品都有适当结构化的文档,让初学者和长期用户都能轻松阅读。我认为文档无法摆脱混乱有几个原因:
通过观察优秀技术文档的组织结构,如Unix手册、Spring Boot或React,你会发现它们都是结构化的。主要用法是根据索引浏览感兴趣的内容。
一般来说,编写技术文档基本上意味着编写类似的结构化文档。结构化文档不仅是目前最主流的文档组织方式,在可预见的未来也将如此。
保持清晰的结构绝非易事。作者很幸运地看到了一种确保正确生成结构化文档的模式:文档象限。
在坐标系中,将象限分为两个轴描述文档的属性。横轴描述文档的使用场景是倾向于工作还是学习,纵轴描述是倾向于理论还是实践。这四个象限分别是教程、操作指南、参考和解释:
图片
文档象限为其内容的呈现定义了明确的界限,使文档看起来简单易懂,更适合对外输出,并帮助用户快速入门。
除了结构化文档之外,似乎还有另一种组织文档的方式:基于图形,并且正在获得影响力。通常,为了保持文章的简洁性和连贯性,我喜欢使用链接文本指出其他地方的相关概念。一旦你深入几层链接,你会发现文档承载的知识很快形成一个大网络。"知识图谱"这个术语恰如其分。自2012年Google知识图谱发布以来,知识图谱的主要应用仍在搜索引擎和文献检索领域。像logseq这样的产品采取了不同的方法,通过加强知识之间的联系,以图形化方式组织文档。其主要用法涉及关键词搜索结合跳转到相关内容(链接引用)。
在使用 logseq 时,我发现这种方法更符合人类在大脑中构建知识模型的方式,有助于深入全面地理解问题。这与Luhmann的"Zettelkasten方法"产生共鸣。
我认为,基于图形的文档组织更适合作为团队的知识库,用于团队内部的知识生产和管理。这与其主要操作模式有关。虽然我认为关键词搜索是一种有效的方法,但它对新用户的搜索能力提出了挑战。
选择参考
当你开始构建文档时,即使没有任何考虑,你也应该使用一些文档工具或协作平台来保存你编写的文档。我了解一些常用的文档工具:
文档生成工具:
文档托管和协作:
图形化文档工具:
这些文档构建方法和工具有什么用途?世界上可能没有完美的软件工具或系统能满足所有个性化需求。当你选择Google Docs进行协作编辑时,你将不得不处理大量样式调整。当你使用Logseq作为团队的内部知识库时,其独特的文档标记格式使得迁移到其他工具变得困难。这令人沮丧!因此,构建文档也需要类似的技术决策工作来确定适合的解决方案。这意味着在困难的权衡中做出选择,选择一个满足要求的解决方案,其优点仍然鼓舞人心,而缺点是可以容忍的。
值得注意的是,具备编写文档的能力并不是唯一要求;在选择解决方案时,我们似乎更重视功能之外的重要特性。是的,文档构建也应该满足可预见的非功能性需求:
令人兴奋的文档构建解决方案
使用Document Zenith组织内容,保存在Github等托管平台上,并使用Sphinx生成电子书进行发布,或生成HTML进行私有部署。
优点:
缺点:
使用logseq作为知识库,并将文档保存在Github等托管平台上。
优点:
缺点:
优点:
缺点:
本文链接：http://www.28at.com/showinfo-26-112739-0.html我们一起聊聊如何编写技术文档
声明：本网页内容旨在传播知识，若有侵权等问题请及时与本网联系，我们将在第一时间删除处理。邮件：2376512515@qq.com
上一篇： 这八 个常见的前端开源库，你一定要知道！
下一篇： Python十大经典项目与实战案例
Copyright © 2016-2023 天津谷骐科技有限公司 版权所有 sitemap.xml
违法及侵权请联系：2376512515@qq.com 津ICP备18001702号
津公网安备 12010102000574号
