小议程序员编写技术文档

   

    一提到写文档，可能很多程序员可能会不屑一顾，但是，无论处于规范开发流程，还是就于逃避嫌责的目的，能够将自己所从事的工作用文档描述记录下来，还是一件很有成就感的事情，抛开其功用不谈，就个人的成长进程看，也是一个循序渐进式的好习惯，还是值得大家稍微关注一下的。

    昨天在和同事的一次交流过程中，就自己编写的讲演文档得到大家的一些有益反馈，不敢独享，晒出来和大家一起分享：首先，要明确文档的应用人群和该人群对其内容的偏好程度，因为人越多，需求点可能就会越多，而我们往往会采取一条主观内容路线的方式进行串接、讲解，这样的逻辑顺延效果主要发生在我们自身，而对于听众来说，可能就很难达到进一步的共鸣了，但，这一点往往不被我们察觉，自我感觉思路清晰，侃侃而谈，就认为自己交流的够清晰，其实不然，听众对该内容不出意外都会较我们少很多，就我们记录的文档内容，可能很难将这些内容进行串接，进而形成一个清晰的概念，于是降低了交流效果，加上大家又比较晦涩，可能不会就过多的内容进行异议，于是……

    如何才能有所改进呢？

（1）在编写文档前，就目标群体进行一下简短的需求调研
（2）将文档的理解点尽量降低，由浅入深地进行介绍，并尽量将一些要点醒目标出，方便温习和查找
（3）文档中尽量使用图释来记录信息，文字内容要少而精，但是切忌图释为取彩而忘本，华丽并不能代替标准的信息传达
（4）根据文档进行讲解的时候，最好能够同时使用实时系统进行辅助，要擅于使用好投影仪等讲解工具
（5）注意大家的意见反馈，就讲解过程中出现的一些不能马上回答的问题，要在交流后第一时间反馈给大家