技术文档写作指南

一个成功且可持续的项目,除了良好的架构设计和高质量的代码外,清晰且易于理解的技术文档也是必不可少的一部分。本文结合自己工作中文档写作的一些经验,来说说如何把文档写好。


可能是因为长期写博客的缘故,在写作这个事儿上,我还是有比较严苛的要求的。技术文档和技术博客在很多方面有相似之处,比方说都是写给技术人员(爱好者)看的。在我看来,很多现在网上的技术博客基本上连技术文档的要求都达不到,或者说文档和博客各占一点,半桶水瞎晃荡。简单来说,博客重在原理与引起读者的兴趣与思考,文档重在细节与方便技术人员解决问题,那这个标准去套,应该就能看出问题所在了。

为什么要写文档

前面说文档和博客的相似,最主要是在技术层面上的相似,甚至眼光放广一点,跟写代码也非常相似,都需要好的设计与架构。而为什么要写文档呢?大约有以下原因:

  • 项目合作需要:比方说前后端分离之后,利用接口进行连接,那么需要接口文档。
  • 项目维护需要:总体项目开发完成后,维护人员和后期开发人员需要相关文档来照看工作。
  • 思路整理需要:通过撰写技术文档,可以梳理好整个系统技术相关思路,更加负责的开发人员会在这个过程中进行优化,使系统更好
  • 技术积累需要:通过抽取一些与业务无关的部分,能够在之后的开发中进行复用,就需要文档支持

简单来说,就是 总结 -> 积累 -> 提高 -> 复用 的过程。

怎么写好文档

我们都希望接手的工作有优秀的文档,但是写文档的时候却常常过于随便。所以我们不妨从『好』文档的标准说起:

  • 准确:不会给人模棱两可的感觉
  • 清晰:不会给人写了很多但不知道写了啥的感觉
  • 完整:不会给人话说到一半戛然而止的感觉
  • 简洁:不会给人没话找话说的感觉
  • 有组织:不会给人不知道要去哪里看什么内容的感觉
  • 可读性好:不会给人每个字都认识但就是看不懂的感觉
  • 任务导向:不会给人跑题不说重点的感觉。

总结一下,其实就是信息架构的能力,是不是发现和代码架构很像?再延伸一些,是不是想到了各种框架?什么 MVC 什么 MVVM 其实不就是某种意义上的层次模块分明吗?

其实凡是需要进行组织的事物,都需要架构能力。好的架构师一定是善于观察善于思考善于提炼的,这些能力在写代码中可以训练,在写文档写博客中同样可以训练。而阅读各种经典,其实就是在向各类牛人们学习,为什么别人这么写我看得爽,我能不能也这么写。一旦有了这个思路,就不怕不知道怎么提高了。

从这个角度出发,来具体给出一些建议吧,因为基于自己的经验,不会特别全面,如果需要全面学习的话,可以去看看技术写作的相关书籍。

  1. 总分总:这个从小时候就常用的方式可以说是最符合人类思维习惯的结构。如果要用比较时髦的词就是『金字塔原理』,无论是正金字塔还是倒金字塔,可以根据需要进行选择。
  2. 一图胜千言:涉及到诸多概念及其相关联系时,不要过多解释,画一个清晰的图,比什么效果都好。不需要太复杂,简单的 UML 已经足够。
  3. 看人下菜:针对不同的群体要有不同的写作侧重点。如果是给运维人员看的,那么重点是要说清楚各个操作以及相关逻辑;如果是给非技术人员看的,一定要尽量『看图说话』,联系他们能够理解的概念来跨越不同职业的鸿沟;如果是给交接的技术同事看的,重点是架构设计以及代码原理。
  4. 少即是多:文档太长,自己更新起来累,别人看起来也累,维护起来更累。所以去掉各类套话,说重点,并保证及时更新。
  5. 理论结合实际:涉及需要操作或者修改的部分,一定要配上简单的例子,否则别人连如何去开始第一步都不知道。
  6. 我用 Markdown:简单、够用,这就是唯一的理由。

题外话

很多时候我们在面对各种做不完的需求时,最先牺牲的就是文档质量,而整个项目的腐化就是从一点一滴开始的。努力安排好时间,不要降低对自己对项目的要求,需求仔细评估排期,一旦做了,就一次做好。否则如果是长期项目,就是坑自己;如果是临时交接,就是坑别人。为什么不可以直接把事情做好,非要后面辛辛苦苦擦屁股搞得好像很努力很负责一样呢?

要我说,一开始没做好,就是最大的不负责。

捧个钱场?