作者 | 蔡正锋
软件开发中，为你的软件系统编写文档并不是一件新鲜的事情。几乎所有人都明白这样的道理：
你的软件产品如何优秀对用户来说并不是最重要的，因为你的文档如果不够优秀，用户不会使用它！即便用户在某些情况下不得不使用你的产品，没有好的文档，用户无法高效使用或者以错误的方式使用你的产品。
不幸的是，鲜少能见到关于如何正确组织技术文档的实践及方法论。团队工作中，编写文档仍面临挑战。
编写技术文档这个任务看起来总是：优先级不够高，特别花时间并且没有立竿见影的正反馈！于是文档编写被一推再推，直至在某些时刻不得不做，比如新人要上项目了，我的开源产品要发布了，才震惊地发现我竟没有文档。文档最后被随意编写，以至于完成后就被彻底忽视。随着系统的演进，这些文档慢慢脱节，变成谎言！这个论断乍一看如此地荒谬，可是却在我身边常常发生。
如同代码编写一样，混乱的结构是相当致命的。我们能使用类似于technical-writing-template这样，基于模板约定的方式使得单篇文章的质量达到一定的水准。然而在复杂的软件系统中，高质量的单篇显然是杯水车薪的。事实上，众多优秀的软件产品它们基本都具备恰到好处的文档，清晰的结构使得初学者和长期用户读起来都毫不费力。我以为，未能使文档免于混乱的原因有以下几点：
通过观察优秀技术文档的组织形式，诸如unix manual、Spring boot或者React，你会发现它们都是结构化的。主要使用方式是按照索引查阅感兴趣的内容。
通常，所谓编写技术文档，基本意味着编写类似的结构化文档。结构化文档不仅仅是当前最为主流的文档组织方式，在可预见的未来也会如此。
保持清晰的结构绝非易事，笔者深感幸运能够看到一种确保正确生成结构化文档的模式：文档象限。
在一个坐标系下，划分象限的两条轴描述了文档所具有的属性，横轴描述文档的使用场景是偏于工作的还是偏于学习的，纵轴描述文档是偏于理论的还是偏于实践的。这四个象限分别是tutorials，how-to guides，reference和explanation：
图片
图片
文档象限将其内容呈现方式划定了明确的边界，让文档看起来简单明了，更适合对外输出，帮助用户快速上手。
结构化文档之外似乎还存在另一种文档组织方式：图谱化，并且初具影响力。很多时候，为了保持文章的简洁和内聚，我喜欢使用链接文字将一个相关概念指向别处。一旦顺着链接深入几层，就会发现文档所承载的知识很快组成一张大网。知识图谱一词简直恰如其分。自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号
