当前位置:首页 > 科技  > 软件

如何编写技术文档?

来源: 责编: 时间:2023-08-20 23:16:45 522观看
导读作者 | 蔡正锋软件开发中,为你的软件系统编写文档并不是一件新鲜的事情。几乎所有人都明白这样的道理:你的软件产品如何优秀对用户来说并不是最重要的,因为你的文档如果不够优秀,用户不会使用它!即便用户在某些情况下不得

作者 |  蔡正锋xWU28资讯网——每日最新资讯28at.com

软件开发中,为你的软件系统编写文档并不是一件新鲜的事情。几乎所有人都明白这样的道理:xWU28资讯网——每日最新资讯28at.com

你的软件产品如何优秀对用户来说并不是最重要的,因为你的文档如果不够优秀,用户不会使用它!即便用户在某些情况下不得不使用你的产品,没有好的文档,用户无法高效使用或者以错误的方式使用你的产品。xWU28资讯网——每日最新资讯28at.com

不幸的是,鲜少能见到关于如何正确组织技术文档的实践及方法论。团队工作中,编写文档仍面临挑战。xWU28资讯网——每日最新资讯28at.com

xWU28资讯网——每日最新资讯28at.com

面临的挑战

仓促地开始和结束

编写技术文档这个任务看起来总是:优先级不够高,特别花时间并且没有立竿见影的正反馈!于是文档编写被一推再推,直至在某些时刻不得不做,比如新人要上项目了,我的开源产品要发布了,才震惊地发现我竟没有文档。文档最后被随意编写,以至于完成后就被彻底忽视。随着系统的演进,这些文档慢慢脱节,变成谎言!这个论断乍一看如此地荒谬,可是却在我身边常常发生。xWU28资讯网——每日最新资讯28at.com

混乱的结构

如同代码编写一样,混乱的结构是相当致命的。我们能使用类似于technical-writing-template这样,基于模板约定的方式使得单篇文章的质量达到一定的水准。然而在复杂的软件系统中,高质量的单篇显然是杯水车薪的。事实上,众多优秀的软件产品它们基本都具备恰到好处的文档,清晰的结构使得初学者和长期用户读起来都毫不费力。我以为,未能使文档免于混乱的原因有以下几点:xWU28资讯网——每日最新资讯28at.com

  • 文档是由多个人编写的。《解析极限编程》中描述一个XP团队中会有“文档撰写员”的角色。即便敏捷实践大行其道的今天,敏捷团队中,不论是成熟的“角色是帽子”,还是传统的“角色是岗位”,都大概很少会见到“文档撰写员”这一角色。文档是由不同的人编写不同的部分,再组合而成的,混乱是自然而然的结果。
  • 缺少对抗混乱的模式。不同于软件编写,我们有架构风格这样深入人心的默认约定。甚至有C4 model来可视化软件架构,帮助团队保持一致的认知,并使架构有序地演进。文档的编写除了本文将要介绍的文档象限之外,并未发现任何一种有较大影响力的编写模式。

两种组织方式

结构化文档

通过观察优秀技术文档的组织形式,诸如unix manual、Spring boot或者React,你会发现它们都是结构化的。主要使用方式是按照索引查阅感兴趣的内容。xWU28资讯网——每日最新资讯28at.com

通常,所谓编写技术文档,基本意味着编写类似的结构化文档。结构化文档不仅仅是当前最为主流的文档组织方式,在可预见的未来也会如此。xWU28资讯网——每日最新资讯28at.com

保持清晰的结构绝非易事,笔者深感幸运能够看到一种确保正确生成结构化文档的模式:文档象限。xWU28资讯网——每日最新资讯28at.com

在一个坐标系下,划分象限的两条轴描述了文档所具有的属性,横轴描述文档的使用场景是偏于工作的还是偏于学习的,纵轴描述文档是偏于理论的还是偏于实践的。这四个象限分别是tutorials,how-to guides,reference和explanation:xWU28资讯网——每日最新资讯28at.com

图片图片xWU28资讯网——每日最新资讯28at.com

图片图片xWU28资讯网——每日最新资讯28at.com

文档象限将其内容呈现方式划定了明确的边界,让文档看起来简单明了,更适合对外输出,帮助用户快速上手。xWU28资讯网——每日最新资讯28at.com

图谱化文档

结构化文档之外似乎还存在另一种文档组织方式:图谱化,并且初具影响力。很多时候,为了保持文章的简洁和内聚,我喜欢使用链接文字将一个相关概念指向别处。一旦顺着链接深入几层,就会发现文档所承载的知识很快组成一张大网。知识图谱一词简直恰如其分。自2012年谷歌知识图谱发布以来,知识图谱的主要用武之地仍在搜索引擎,文献检索领域。有诸如logseq这样的产品另辟蹊径,强化知识之间的链接,以图谱化的方式组织文档。其主要使用方式是关键字检索加上相关内容(linked reference)的跳转。xWU28资讯网——每日最新资讯28at.com

在使用logseq的过程中,我发现这种方式更契合人类在大脑中构建的知识模型,有利于深刻又全面地理解问题。这与卢曼的《卡片笔记写作法》有异曲同工之妙。xWU28资讯网——每日最新资讯28at.com

笔者以为,图谱化的文档组织方式在团队中更适合知识的生产和管理,即作为团队的知识库。原因与其主要使用方式有关。尽管我认为关键字检索不失为一种高效的方式,但是给新用户的检索能力提出了挑战。xWU28资讯网——每日最新资讯28at.com

选型参考

当你开始着手构建文档的时候,即便不作任何考量,也要借助一些文档工具甚至协作平台来保存你编写的文档。笔者了解到一些常用的文档工具:xWU28资讯网——每日最新资讯28at.com

文档生成工具:xWU28资讯网——每日最新资讯28at.com

  • sphinx
  • docusaurus

文档托管与协同:xWU28资讯网——每日最新资讯28at.com

  • google doc
  • confluence

图谱化文档工具:xWU28资讯网——每日最新资讯28at.com

  • logseq

了解到这些文档构建方式和工具有什么用呢?这个世界大概不存在一个完美的软件工具或者系统使得所有的个性化需求都被满足。当你为了协同编辑选择了google doc,将不得不面对大量的样式调整工作。当你使用logseq作为团队内部的知识库,其特有的文档标记格式使其难以迁移到其他的工具里。这真让人沮丧!于是乎,构建文档也要进行类似技术选型的工作,确定一个合适的方案。这意味着要在艰难的权衡之下,选择能满足需求的方案,其优点仍令人振奋,其缺点还可以忍受。xWU28资讯网——每日最新资讯28at.com

值得注意的是,具备能写文档这样的功能并非唯一的需求,选择方案时我们似乎更看重功能以外的重要特性。没错,文档构建也该满足可预见的非功能性需求:xWU28资讯网——每日最新资讯28at.com

  1. 可移植性:在可预见的未来,是否需要将文档迁移到另一个环境?
  2. 可用性:用户体验与易用性,协作能力,国际化
  3. 合规性
  4. 可访问性:仅内部网络有效?完全公开还是要通过授权鉴权?
  5. 存档:文档如何被变更,保存,备份?
  6. ...

令人激动的文档构建方案

sphinx + 文档象限 + Git

利用文档象限组织内容,利用Github等托管平台保存,sphinx将其生成为电子书发布,或者生成HTML进行私有化部署。xWU28资讯网——每日最新资讯28at.com

(1) 优点xWU28资讯网——每日最新资讯28at.com

  • 良好的国际化支持
  • 极高的灵活性
  • sphinx高度可配置,拥有成熟的生态
  • 文档托管及私有化部署具有众多的代替选项
  • 只依赖Python运行环境,具有极高的可移植性,可以随软件版本迭代一起更新,维护,部署,纳入迭代管理

(2) 缺点xWU28资讯网——每日最新资讯28at.com

  • 要求文档的贡献者熟悉两种技术:Git 和 markdown

:memo: Note: 这里有一个How-to guide: 于sphinx上实践文档象限xWU28资讯网——每日最新资讯28at.com

logseq

使用loqseq作为知识库,利用Github等托管平台保存文档xWU28资讯网——每日最新资讯28at.com

(1) 优点xWU28资讯网——每日最新资讯28at.com

  • 能够以极低的成本构建知识图谱,作为知识库
  • 使用方式是关键字检索和关联内容跳转,这是一种让人更容易聚焦于思考的交互方式

(2) 缺点xWU28资讯网——每日最新资讯28at.com

  • 使用方式是关键字检索和关联内容跳转,并不适合新手快速上手
  • 需要每一个用户安装logseq的客户端
  • 要求文档的贡献者熟悉两种技术:Git 和 markdown
  • 难以对外发布内容

google doc/confluence + 文档象限

(1) 优点xWU28资讯网——每日最新资讯28at.com

  • 多人协同
  • 内建的鉴权授权,支持单点登录(sso)
  • 大众化的产品,易用性好

(2) 缺点xWU28资讯网——每日最新资讯28at.com

  • 需要手动管理存档备份,容易造成混乱
  • 可移植性差

总结

慎重地审视这些方案各自的优缺点后,我发现采用结构化的文档组织方式时,文档象限总是有用武之地,似乎能够保证我们生成“不太坏”的文档。同时,笔者建议慎重选择图谱化文档,你可能并没有做好因文档改变自己工作习惯的准备,你可能还需要同时维护一份结构化文档。xWU28资讯网——每日最新资讯28at.com

本文链接:http://www.28at.com/showinfo-26-6163-0.html如何编写技术文档?

声明:本网页内容旨在传播知识,若有侵权等问题请及时与本网联系,我们将在第一时间删除处理。邮件:2376512515@qq.com

上一篇: 基于模块联邦与大仓模式的商家巨石应用拆分实践

下一篇: 基于静态编译构建微服务应用

标签:
  • 热门焦点
  • 俄罗斯:将审查iPhone等外国公司设备 保数据安全

    俄罗斯:将审查iPhone等外国公司设备 保数据安全

    iPhone和特斯拉都属于在各自领域领头羊的品牌,推出的产品也也都是数一数二的,但对于一些国家而言,它们的产品可靠性和安全性还是在限制范围内。近日,俄罗斯联邦通信、信息技术
  • 六大权益!华为8月服务日开启:手机免费贴膜、维修免人工费

    六大权益!华为8月服务日开启:手机免费贴膜、维修免人工费

    8月5日消息,一年一度的华为开发者大会2023(Together)日前在松山湖拉开帷幕,与此同时,华为8月服务日也式开启,到店可享六大专属权益。华为用户可在华为商城Ap
  • 2023 年的 Node.js 生态系统

    2023 年的 Node.js 生态系统

    随着技术的不断演进和创新,Node.js 在 2023 年达到了一个新的高度。Node.js 拥有一个庞大的生态系统,可以帮助开发人员更快地实现复杂的应用。本文就来看看 Node.js 最新的生
  • 谷歌KDD'23工作:如何提升推荐系统Ranking模型训练稳定性

    谷歌KDD'23工作:如何提升推荐系统Ranking模型训练稳定性

    谷歌在KDD 2023发表了一篇工作,探索了推荐系统ranking模型的训练稳定性问题,分析了造成训练稳定性存在问题的潜在原因,以及现有的一些提升模型稳定性方法的不足,并提出了一种新
  • 为什么你不应该使用Div作为可点击元素

    为什么你不应该使用Div作为可点击元素

    按钮是为任何网络应用程序提供交互性的最常见方式。但我们经常倾向于使用其他HTML元素,如 div span 等作为 clickable 元素。但通过这样做,我们错过了许多内置浏览器的功能。
  • 大厂卷向扁平化

    大厂卷向扁平化

    来源:新熵作者丨南枝 编辑丨月见大厂职级不香了。俗话说,兵无常势,水无常形,互联网企业调整职级体系并不稀奇。7月13日,淘宝天猫集团启动了近年来最大的人力制度改革,目前已形成一
  • 阿里大调整

    阿里大调整

    来源:产品刘有媒体报道称,近期淘宝天猫集团启动了近年来最大的人力制度改革,涉及员工绩效、层级体系等多个核心事项,目前已形成一个初步的“征求意见版”:1、取消P序列
  • 超闭合精工铰链 彻底消灭缝隙 三星Galaxy Z Flip5与Galaxy Z Fold5发布

    超闭合精工铰链 彻底消灭缝隙 三星Galaxy Z Flip5与Galaxy Z Fold5发布

    2023年7月26日,三星电子正式发布了Galaxy Z Flip5与Galaxy Z Fold5。三星新一代折叠屏手机采用超闭合精工铰链,让折叠后的缝隙不再可见。同时,配合处
  • 质感不错!OPPO K11渲染图曝光:旗舰IMX890传感器首次下放

    质感不错!OPPO K11渲染图曝光:旗舰IMX890传感器首次下放

    一直以来,OPPO K系列机型都保持着较为均衡的产品体验,历来都是2K价位的明星机型,去年推出的OPPO K10和OPPO K10 Pro两款机型凭借各自的出色配置,堪称有
Top