我所知道的技术写作

工作几年下来, 技术水平不行, 但我对文档写作的要求还挺高的. 平日里见过的高质量文档, 更是凤毛麟角, 因此写点有的没的, 作为公司内部分享, 同时丰富一下周末生活.

文档也是代码

如果说代码是教机器做事情, 那文档便是在以人为硬件, 在”教人做事情”. 代码写不好, 程序便会跑崩, 或者性能差. 文档写不好, 读者就会吃苦头, 甚至更糟的情况, 整个团队都要持续地付出代价. 很多人心态上就把文档给看低了, 随随便便狗出来点东西搪塞过去, 殊不知这些行为会持续向未来的工作收税, 让你的团队不知不觉地浪费宝贵时间, 损害效率.

既然说文档也是代码, 那么编程的一系列基本原则, 在文档写作的世界里也是金科玉律, 比如 DRY (Don’t Repeat Yourself), KISS (Keep It Simple Stupid). 我将本着文档即代码的精神, 分享我对文档写作的一贯看法, 并指出一些常见错误.

持续维护

就像代码一样, 文档也是需要持续维护的. 软件开发如此敏捷迅速, 如果匹配的文档不持续地积极维护, 那倒不如没有文档, 直接问 owner 虽然低效, 但起码能获得正确的信息. 我就曾不少次对着过期的错误文档, 活生生浪费掉一个又一个下午.

所以下次你若是需要起首一份技术文档, 一定要把他纳入到维护体系里: 每次开发迭代, 都梳理下是否需要一并更新文档. 为此, 我更喜欢在 Git Repo 里直接撰写文档, 文档离代码如此之近, 更不容易淡忘维护文档的责任. 现在很多互联网公司都在用自己的在线文档协作方案, 同事们轻轻松松就能创建一份新的在线文档, 开开心心写完发布, 很容易就抛到脑后, 日后随着开发迭代, 谁也想不起来这份文档是需要一并更新的. 如果有可怜虫翻开了这份文档, 对着不适用的内容浪费时间, 他会觉得很傻逼, 他会想要杀人.

整合信息

信息分散是非常糟糕, 非常恶心和邪恶的事情. 在文档的各种错误实践里, 这个恐怕是我最痛恨的一项.

什么是信息分散? 就是本来应汇集一处的信息, 分散在各种地方: Trello (或者别的任务管理系统), IM (比如飞书, Slack), Git Repo (README), 在线文档. 听上去或许没什么大问题, 但就是这样的小事, 可以让整个文档体系分崩离析.

我一向坚持, 如果要撰写文档, 教人做事, 那就应该严格整合信息, 创造一个 Single source of truth. 而不是今天心情好, 写一份文档, 下次有什么急事儿, 就在群里发布, 把先前的文档忘一干二净. 这就像是老师上课不给教材, 而是每节课开头给你发几张纸, 有时候是平装课本撕下来的书页, 有时候是便签贴纸, 有时候甚至是密密麻麻写了小字的厕所卫生纸, 你绝对没办法把这些信息收藏整理好, 在今后再次用到的时候能迅速翻出来参考.

信息分散还造成信息的重复 (代码写多了, 看到 Duplication 这个词就会天然有一种警觉), 具体就是, 在线文档里已经写过的内容, 在 Trello 里重复写一遍. 明明在项目 README 里已经写明的内容, 在群里问到的时候, 再重新说一遍, 而不是直接引用文档作答. 同一份信息在不同的地方都重复书写, 并且随着情况变化, 每一次写出来的都有些细微不同. 下次用到这些信息时, 谁都不知道应该参考哪一份. 我经历过的所有公司都存在这样的文档乱象, 所以在这件事上, 不是比能力, 而是”比想法”, 比文化.

那怎么办啊? 怎么解决这些问题? 恐怕没啥好办法, 就是要求大家写和说的时候三思吧, 该补充文档, 用文档来回答的, 一定不要现场敲键盘来写. 培养出维护文档的文化, 才能让文档为你工作. 不过能想到这些的人, 恐怕都已经做的不错了, 做不好的人, 也已经积重难返. 只能说如果有机会重来的话, 尽量吧

文笔水平

Google 甚至有个技术写作课程, 我用英文写不了几个字, 所以并未详读. 我觉得吧, 只要能把事情讲清楚, 用什么办法都可以. 但在实际工作当中, “把事情讲清楚”其实是非常高的要求, 若是对方能做到, 我已经肃然起敬.

我见过的不少内部文档, 都是信息堆砌, 没有条理. 大部分这种情况, 只是纯粹的粗心写作: 不把文档当回事儿, 觉得把信息粘贴进去了, 就足够了. 没有基本的叙事逻辑, 目录结构, 甚至格式也乱七八糟, 各种字号字体颜色混用. 不过在这公开空间, 就不拿内部文档举例了.

互联网这么理科向的行业, 朋友们若真的有心, 其实都能条理清晰地进行写作. 文笔质量低下, 可能并不影响这份文档正常工作 (就算厕所有点味儿, 我也就硬着头皮用了), 但还是尽量用心写吧, 一份逻辑通顺, 排版规整的文档, 能让用到的同事心情都好一些.

一图胜千言, 但有时也未必

如果是在介绍技术架构, 或者是撰写某种新闻稿, 那必定是一图胜千言. 但很多技术文档的用途是叙述操作步骤, 或者介绍工具的使用, 这种场景还请斟酌图片的使用, 我就在文档里见过不少没有意义的图片:

常见错误: 无用图片

我们都不是在上学, 不需要堆字数, 堆页数了, 不要贴没有意义的图片. 比如在某份文档里, 作者对软件的下载页面做了截图, 甚至对 Download 按钮还做了划线标红, 这真的有必要吗? 来看这种程度技术文档的人, 谁还不知道如何在官网下载一款软件呢?

常见错误: 信息量低

三言两语能说清楚的事情, 尽量不要用图片, 比如下图就是想让你点个按钮, 意思非常简单, “选择地域, 在实例列表处, 点击更多-购买相同配置”. 区区几十字节的内容, 却要用几千字节的截图来表示, 这种无聊的事情做多了, 不仅让你的文档信息密度降低, 加载起来还会变慢.

请记住, 文字表达不好的情况, 才考虑使用图片. 你可能觉得多放一些操作界面截图, 能给人一种”手把手教你”的感觉, 但大部分现代软件和网页, 操作界面还是很简明易懂的, 并不需要你做这种费力不讨好的事情. 而且注意, 操作界面可能会变的, 万一哪个按钮或者板块挪了位置, 你的文档是不是应该对所有图片做梳理, 将所有截图重新拍摄?

从前的某些内部文档里, 我还见过把 API 数据结构体用截图来代替的, 我没能在公开空间找到示范, 就不详述了, 目前接触到的大厂 API 文档, 维护还是相当好的.