作者 | 蔡正锋
软件开发中，为你的软件系统编写文档并不是一件新鲜的事情。几乎所有人都明白这样的道理：
你的软件产品如何优秀对用户来说并不是最重要的，因为你的文档如果不够优秀，用户不会使用它！即便用户在某些情况下不得不使用你的产品，没有好的文档，用户无法高效使用或者以错误的方式使用你的产品。
不幸的是，鲜少能见到关于如何正确组织技术文档的实践及方法论。团队工作中，编写文档仍面临挑战。
图片
图片
文档象限将其内容呈现方式划定了明确的边界，让文档看起来简单明了，更适合对外输出，帮助用户快速上手。
结构化文档之外似乎还存在另一种文档组织方式：图谱化，并且初具影响力。很多时候，为了保持文章的简洁和内聚，我喜欢使用链接文字将一个相关概念指向别处。一旦顺着链接深入几层，就会发现文档所承载的知识很快组成一张大网。知识图谱一词简直恰如其分。自2012年谷歌知识图谱发布以来，知识图谱的主要用武之地仍在搜索引擎，文献检索领域。有诸如logseq这样的产品另辟蹊径，强化知识之间的链接，以图谱化的方式组织文档。其主要使用方式是关键字检索加上相关内容（linked reference）的跳转。
在使用logseq的过程中，我发现这种方式更契合人类在大脑中构建的知识模型，有利于深刻又全面地理解问题。这与卢曼的《卡片笔记写作法》有异曲同工之妙。
笔者以为，图谱化的文档组织方式在团队中更适合知识的生产和管理，即作为团队的知识库。原因与其主要使用方式有关。尽管我认为关键字检索不失为一种高效的方式，但是给新用户的检索能力提出了挑战。
当你开始着手构建文档的时候，即便不作任何考量，也要借助一些文档工具甚至协作平台来保存你编写的文档。笔者了解到一些常用的文档工具：
文档生成工具：
文档托管与协同：
图谱化文档工具：
了解到这些文档构建方式和工具有什么用呢？这个世界大概不存在一个完美的软件工具或者系统使得所有的个性化需求都被满足。当你为了协同编辑选择了google doc，将不得不面对大量的样式调整工作。当你使用logseq作为团队内部的知识库，其特有的文档标记格式使其难以迁移到其他的工具里。这真让人沮丧！于是乎，构建文档也要进行类似技术选型的工作，确定一个合适的方案。这意味着要在艰难的权衡之下，选择能满足需求的方案，其优点仍令人振奋，其缺点还可以忍受。
值得注意的是，具备能写文档这样的功能并非唯一的需求，选择方案时我们似乎更看重功能以外的重要特性。没错，文档构建也该满足可预见的非功能性需求：
利用文档象限组织内容，利用Github等托管平台保存，sphinx将其生成为电子书发布，或者生成HTML进行私有化部署。
(1) 优点
(2) 缺点
:memo: Note: 这里有一个How-to guide: 于sphinx上实践文档象限
使用loqseq作为知识库，利用Github等托管平台保存文档
(1) 优点
(2) 缺点
(1) 优点
(2) 缺点
慎重地审视这些方案各自的优缺点后，我发现采用结构化的文档组织方式时，文档象限总是有用武之地，似乎能够保证我们生成“不太坏”的文档。同时，笔者建议慎重选择图谱化文档，你可能并没有做好因文档改变自己工作习惯的准备，你可能还需要同时维护一份结构化文档。
本文链接：http://www.28at.com/showinfo-26-6163-0.html如何编写技术文档？
声明：本网页内容旨在传播知识，若有侵权等问题请及时与本网联系，我们将在第一时间删除处理。邮件：2376512515@qq.com
下一篇： 基于静态编译构建微服务应用
Copyright © 2016-2023 天津谷骐科技有限公司 版权所有 sitemap.xml
违法及侵权请联系：2376512515@qq.com 津ICP备18001702号
津公网安备 12010102000574号
