技术文档的写作
摘要
写技术文档是非常有意义的，然而它不能直接产生价值，而是一个长期自我提升的过程。写技术文档的最大价值不在于帮助别人了多少，而在于它对写作的人的要求非常高，从而倒逼自己去学习和复盘。然而写文档的路上总会遇到很多问题和困难，所以本文通过对话的形式, 向读者展示了自己的个人看法。
目录
1 为什么要聊这件事?
2 写文档的意义具体表现在哪?
3 为什么很多人讨厌写文档?
4 既然如此, 为什么还要非写不可?
5 你说的都太宽泛, 给出几条实际的做法?
6 如果我还是不想写文档呢?
7 我很忙真的应该写文档吗?
8 应该指定写文档的规范吗?
9 写文档, 我感觉没什么好处?
10 我们应该有什么样的写文档的基础设施呢?
11 我们写文档的时候, 应该注意什么呢?
12 写一篇文档的时候, 我一定要抱着高标准去吗?
13 总结
正文
1 为什么要聊这件事?
答: 这件事非常有意义.
2 写文档的意义具体表现在哪?
答: 意义在于知识的传递. 从自己到读者, 从过去的自己导将来的自己, 从知识消费者到知识生产者, 从无人知晓到思想流传.
3 为什么很多人讨厌写文档?
答: 因为,第一, 写文档不是一件容易的事情, 写不好不如不写, 写好了又浪费时间, 介于中间食之无味弃之可惜. 第二, 写文档没有什么明确的收益, 难以作为考核的目标, 难以作为工作量的体现, 写的一般没人看, 写的好几乎不可能, 高不成低不就, 现实中很多人写的文档就处于这种尴尬的地步.
4 既然如此, 为什么还要非写不可?
答: 参考第#2条, 意义已经很明确了. 关键是如何困难. 写文档的难处必须要理清楚, 写文档的意义也要想清楚.
5 你说的都太宽泛, 给出几条实际的做法?
答: 我的第一个做法就是,
(1) 目标定低一点, 首先, 不要写出很好的文档, 可以当写日记一样慢慢写出自己的想法, 内容大于形式, 如果一开始别人要求你写出很规范的文档, 你又没可以训练过, 那么肯定感觉非常难.
(2) 内容写详细一点. 举个例子, 一条路你去的时候感觉很远,当你走回来的时候,如果体力还好, 你感觉这条路其实不远. 一个地方你陌生的时候感觉很大, 熟悉之后, 你感觉很小, 这都是主观感觉. 当一个事物你不熟悉的时候, 你希望前人给出你详细的文档, 当你熟悉之后, 当你为后人写文档的时候, 你觉得, 嗯, 这一点很简单, 那一点也很简单, 另外一点网上查查资料就知道了, 看看文档就知道了, 嗯, 都没有必要写, 干脆就写一点有挑战性的东西吧. 你这样叫文档吗?
(3) 我们从第(2)点引出一个观点: 写文档不是一个人的事情, 它是两个人的事情, 简单来说是读者和作者的事情, 它需要两者不断互相交流, 才能写出好的文档. 哪些点该写, 哪些点不改写, 是由双方一起互相影响和决定的, 对彼此有帮助才是核心原则. 甚至来说, 一篇好的文档, 它是由很多读者和几个作者之间不停互动, 最后形成的结果. 一边写,一边让你的读者指出哪里他看不懂.
(4) 我们从第(3)点开始说, 什么叫对彼此都有帮助. 首先, 我们要有一个预设, 写文档需要时间成本和精力. 所以不可能什么都写, 芝麻大的事都要写, 所以粒度需要把握. 其次, 写出来要对读者首先有帮助, 如果写的东西过于琐碎, 会让阅读的人容易疲劳且抓不住重点, 如果写的东西过于抽象, 则会让阅读的人迷茫和难以理解, 如果写的东西过于跳跃, 尤其是关键部分的缺失, 会让人抓耳挠腮, 感觉有一道无法逾越的障碍. 如果写的语言过于正式, 会让读者产生距离感, 如果写的过于私密, 则会暴露一些安全问题, 如果写的东西一下子引入过多概念和非必要实体, 则会让读者白白增加学习成本而难以实现文档本身的目的. 因此需要把握一个度, 要具体问题具体分析, 明白最重要的点是什么, 从而让其他一切不重要的东西为重要的东西让路.
(5) 未必要等到结尾才开始写文档, 最好能够在一开始写设计文档, 阐述设计思路和选择, 在中途遇到什么苦难, 也可以记录. 全部堆积到最后的结果就是畏难心理而没有文档, 或者写一些敷衍性的文档交差.
6 如果我还是不想写文档呢?
答 写文档这个事还是对自己有帮助的事情. 爱因斯坦有一句名言, 如果你不能清楚的解释某一件事, 那么你就有可能并不能很好的掌握它. 如果你含糊不清, 难以掌握一件事的来龙去脉, 那么你可能是盲人摸象. 写文档对自身是一个重大的挑战, 也是一个机会.
7 我很忙真的应该写文档吗?
答 文档未必立刻要写, 但是应该在有空的时间补上. 交接给别人, 安全可靠又省心, 还能让自己对全盘有一个复盘, 是一个双赢的行为, 可以查漏补缺. 写文档还是一个伟大而高尚的过程, 有的东西只有你知道, 如果你写出来, 那么对别人来说, 是一个很好的学习过程, 也是一个帮助自己减轻负担的过程, 如果身边的人每天进展缓慢, 因为沟通问题而反复返工, 那么肯定一部分原因是当初文档的缺失, 而造成技术断档了.
8 应该指定写文档的规范吗?
答 一开始,大家都不习惯写文档的时候, 不应该强制. 文档规范应该是参考, 而非强制. 应该是不限文体, 不限形式. 否则就会对写文档的人造成巨大的压力而放弃写文档, 只有当文档文化成熟之后, 才慢慢形成一个团队的统一格式和风格, 它应该足够的简单和符合直觉, 又能尽量解释复杂的流程, 也就是说, 可以很好地保证新人融入进来, 也能把自己的想法很好的表达出来.
9 写文档, 我感觉没什么好处?
答:是的, 我说过. 写文档, 最开始, 写的不好, 没人看, 没人反馈, 自己High, 最后啥都没落下, 所以大家就想, 干脆不写了. 我也反复说过, 写文档, 是一个帮助自己帮助别人的过程. 比如写文档作为一个暴露自己设计和思想的过程, 其实是不断可以反作用与设计本身, 提高对自己的要求. 我们作为读者, 也应该尽量多支持写文档的, 点个赞,收藏一下是最基本的, 如果发现有问题, 或者其他问题, 如果能够给出批评指正, 那么就对作者非常有帮助了, 国外的 StackOverflow 就是一个非常成功的问答社区, 彼此成就.
10 我们应该有什么样的写文档的基础设施呢?
答: 写文档, 一般来说, 有背景介绍, 解决方法, 复杂的还有相关工作, 设计思路介绍, 实现, 越复杂都接近于一个学术和工程论文了. 因此, 我们需要 (1)一种提供多种格式的模板 (2)一种快速发布的渠道 (3)一个快速反馈和获取反馈的工具 我认为这三者是非常重要的.
11 我们写文档的时候, 应该注意什么呢?
答: 注意一定的格式, 比如提供目录, 比如提供摘要和总结, 尽量格式统一整齐, 这样可以节省读者的时间, 可以判断这篇文档对自己有无帮助, 可以快速跳转到有帮助的地方, 最好留下自己的联系方式便于讨论. 这是当我们熟练的时候, 一开始的时候, 就不要有什么要求了,写出来, 随便写的什么就好了,只要你愿意开始, 你就可能发现自己停不下来了, 最重要的是, 先开始, 然后分阶段完成自己的目标.
12 写一篇文档的时候, 我一定要抱着高标准去吗?
答: 大可不必. 写一篇文章的时候, 如果你的读者只有特定的一个人, 或者几个人, 甚至可能没有人, 那么这个时候差不多的把重点说清楚, 简单的说一下流程就够了. 随着读者越来越多, 或者这件事越来越重要, 你就应该持续改进. 文档不是一锤子买卖, 一个好的文档能够获得更多的曝光, 初稿难以完美, 它是由客观现实决定的, 是由你的受众的多少, 事的重要性, 你最大允许时间和精力决定的, 这些都在不断的变化中的, 是需要不断的改进的, 因此是一个长期的过程.
13 总结
本文通过问答的方式, 探讨了一些基本的写文档的意义, 难点, 解决思路, 并且针对文档的困境提出了自己的一个如何改进写文档的基础设施的构想.
