对写技术文档这件事的思考

March 15, 2016

技术管理

最近摊上一件大事,比较麻烦的事,就是写一份技术文档。

文档主题是 Android 客户端的性能规范。临时的被告知我成为了公司性能规范制定小组中,唯一的 Android 成员。我的任务就是和其他方向的几位同事一起负责起草一份性能规范。

在小组的第一次会议中,主持者大概的描述了一下我们的目标,对于怎么制定规范,规范的内容都有些什么,规范的形式,或者格式是什么样的,大家都还是比较模糊的。这是一件大家以前都没有做过的事情。于是简单的沟通后,我们决定分头去思考,分别给出文档,不限形式,不限内容……

于是在后来的几天时间内,我一直处于一个精神恍惚的状态。手头上还有日常的项目,在代码和文档之间来回切换,顿时感觉人是很崩溃的。突然发现写代码确实是一件多么痛快的事情啊。

思考了一下,写文档为何那么痛苦,我大概想出了以下几点

  1. 文笔不行

    作为了一个理科生,不擅长写作从初高中的作文就可以看出来了。高中毕业后就有种解放的感觉,别问我大学是怎么过来的,大学的作业还有抄解决不了的?虽然工作以后还有写写技术博客的习惯,但是在没有任何压力的情况下,基本上都是想到哪写到哪,反正也没人看,自己写完了自己都不爱看。

  2. 技术不行

    我面对的是一份技术文档,一份性能规范,完成之后是会在公司的技术团队实施的,这和我自己瞎写的技术博客区别是很大的。在写的时候,感觉脑子里都是空白的,又好像有很多想法,但是怎么写下来,怎么表达出来?怎么写才能是专业的?而不是写出来让人觉得太 low 了吧。对一些技术细节,理论,概念没有很好的理解的话,真的是没有信心把它写下来。

  3. 思维混乱

    坐着想的时候,思维泉涌,要下笔的时候跟便秘似的,实在受不了了,我在微信上发了一条朋友圈,“写不出文档和拉不屎的感觉是一样的”。后来尝试各种工具,word 文档,思维导图,手写……希望通过这些工具能帮我整理思路,又不敢去尝试那些没有使用过的工具,我怕把时间花在不该花的地方了。

  4. 曾经的坏习惯

    为了写这份文档,我网上搜了一圈,希望能找到一个速成的办法。后来发现这么一个观点支持的人还是比较多的,就是通过自己反复的推敲自己的文章,来提高自己的写作水平。回想我曾经的技术博客,很少有写完了还回去反复修改的,这样的博客是应该没人看。

所以,我也希望从这里开始……

--- EOF ---

添加新评论