文档这件小事

96
javaadu 595a1b60 08f6 4beb 998f 2bf55e230555
0.8 2019.04.06 17:09 字数 1737
cameras-composition-data-1483937.jpg

昨天谈了开会,谈下文档这件小事。下面这张脑图,是来自宝玉老师的软件工程之美中的一篇文章——《你为什么不爱写文档?》,早上我也在朋友圈分享了这篇文章。


文档这件小事.png

程序员届流传着这样的段子:

程序员不喜欢写文档(注释)
程序员不喜欢接手的项目(注释)文档太少。

为什么会产生这样的现象?不喜欢写文档和不喜欢接手的项目文档太少的程序员是同一个人吗?有时候是,有时候不是。段子归段子,文档在软件工程中仍然有其重要的价值:辅助思考、辅助团队沟通和协作、便于交接和维护,从另一方面来说,大脑应该尽量用来思辨,而不应该用来记忆(关于这一点,在GTD工作法中有多次提及)。

在软件项目开发中,只要是要长期维护的项目,就一定需要文档的支持,比方说:在一个重要的架构决策点上,在最开始设计的时候一定是多方案的,在当时的情景(时间、预算、人力、能力)下做的决策和取舍,动机是什么,评审的标准是什么,这些都应该记录下来,否则,这个项目到后面的时候都没有人敢改,即使不得不改,也是改得战战兢兢的。

阅读摘抄

  1. 写作的过程,就是一个思考的过程。写文档,可以让你在写代码之前,梳理清楚思路,想清楚整体架构,比如说哪些工作是重点难点;哪些要依赖其他人,需要及早协商的;哪些是考虑安全性的。
  2. 先写文档,就会抛开代码细节,去站在全局思考。
  3. 不爱写文档,真正的障碍是没想清楚,在心中只有一些未成形的混乱的想法和概念,必须要努力把这些模糊的想法确定化和具体化,才能写出来。换句话说,如果你连文档都写不出来,那又怎么能指望代码写得好呢?
  4. 我有一个习惯,每到一个新的项目组,就会把日常工作中遇到的问题、各种环境配置、一些操作的步骤等,所有以后可能还会遇上的都记录下来,其中一些还会整理到团队的wiki上。一段时间后,这些随手记录下来的内容都会发挥大作用,对于我来说,很多问题就不需要问第二遍了;对于团队来说,随着人员的更替,我记录的这些东西都是最好的一手资料,有新人过来,按照我当初记录的内容,就可以快速上手。
  5. 模仿就是最好的学习写文档的方式。
  6. 项目中很多文档都可以从这样小的内容开始:别人给你讲一个问题的时候记录下来;你给别人讲一个问题的时候记录下来;解决一个技术难题的时候记录下来等。
  7. 平时看到好的图也要注意收集和整理,以后自己写的时候,也可以直接参考,帮你少走很多弯路。
  8. 我比较认同敏捷宣言的观点:文档很重要,但是工作的软件高于详尽的文档,这里面的平衡很重要。
  9. 文档的写作一样需要多练习,写得越多就越熟练。

我的心得

  1. 写文档(写作)可以帮助我进行全面、深度的思考,全面有助于提升我的方案的缜密性,不要遗漏什么关键点,深度有助于我理解问题的本质。
  2. 写文档(写作)可以将一些通用的东西抽象出来,形成方法论;
  3. 写文档(写作)可以帮我记住很多knowhow,提高工作的效率,重复的问题(错误)不会一犯再犯;
  4. 写文档(写作)可以帮我记录自己做过的一些决策,方便将来参考或打脸,总之,多记录,多思考,多验证,这样的日志过得是踏实的。
  5. 写项目计划,有助于我提前站在全局去考虑我要做的事情,例如:有哪些准备工作要做;有哪些点还没有想清楚,需要寻求外部的帮助;有哪些事情是关键点,必须拿到确定的结果。有了这样的计划,剩下执行的过程就是按图索骥,即使偏离了预期,也可以及时发现和调整。
  6. 平常可以注重笔记或者小的片段的记录,这些零碎的想法、问题、记录,积累下来,到时候搜索或整理下就是一篇完整的文档(文章);
  7. 平常要注重素材的收集,看到好的想法、好的图片、好的文档,要注意收集下来(打好标签),在需要的时候就可以调出来参考。
  8. 去年读过一本书——《数文明》,这本书中有个观点非常好:对数据的记录的精细和全面的程度可以反映出文明的高级程度。放在文档这个话题上也一样适用——文档的清晰和全面程度反映了团队对项目的把控力。
  9. 推荐几个我常用的写文档的工具:xmind(或幕布),用于构建思维导图;印象笔记(或语雀),用于写文章或日记;omnigraffie,用于绘制软件工程中用到的各种图表;xnip,在mac上笔记好用的截图软件,支持滚屏截图;ppt(或keynote),ppt是硬技能,不要抵触它。

广告时间

不多说了,很多文章我都读了不下三遍,另外,留言区也非常精彩,跟同学们学习到了很多,欢迎加入学习。


image.png

本号专注于后端技术、JVM问题排查和优化、Java面试题、个人成长和自我管理等主题,为读者提供一线开发者的工作和成长经验,期待你能在这里有所收获。


javaadu
软件工程
Web note ad 1