一封关于“书写文档的提议”信

      中国有句古话叫“授人以鱼不如授人以渔”，说的是传授给人既有知识，不如传授给人学习知识的方法。道理其实很简单，鱼是目的，钓鱼是手段，一条鱼能解一时之饥，却不能解长久之饥，如果想要永远有鱼吃，那就要学会钓鱼的方法。

     往往很多人理解这句话的时候是从“传授者”的角度出发，觉得“应该如何去做，而不应该如何去做，哪一种才是更好的选择”；然而，在某些特定的环境下却需要从 “受众者”的角度去思考，作为一个“受众者”应该明白的问自己“此时此刻，我需要的是什么”。对于一个饥寒交迫的人来说，当然更希望得到那一框鱼以解燃眉 之急，后续的生存并非一定要靠钓鱼才能为继；而对于一个已经解决温饱的人来说，更希望的是掌握钓鱼的技能，以后靠自己的垂钓便能享受到美味的鱼儿。

      作为一个“受众者”，它是利益的所得者，在相应的环境下，明明白白知道自己想要什么才是最重要的。

      对于一个公司来说，同样适用以上的那句古话。从公司的角度来看，可以把公司当作是一个“受众者”，把公司里的员工当作“传授者”。公司处于不同的发展阶段， 对员工的需求会有所不同。每年的这个时候是一个“暗流涌动”的季节，难免会给公司带来一定的挑战。针对这个挑战，对公司来说并不是一件好事，怎么可能把 它说成是“受众者”呢？针对这种问题，从辩证的角度去分析它会显得合理些。

      企业间的人才流动交流，往往都有一段时间用来重新布置及安排任务，而这个安排的任务往往因时、因势而定。

      如果公司的一切条件都已具备，那么让员工尽量去完成手头上的项目，对于公司这个“受众者”来说的话是利益最大化的。如果没有一个后来者能够顶替任务的话，那么尽量留下一些技术文档，对于公司来说才是利益最大化的。

     我们的公司还很年轻，目前依旧处于发展的阶段，某些方面还不是很完善。针对公司现有的状况，谈谈我个人所看到的现象。之前接替服务器端工作的时候，尝试着去看wiki上的相关文档，发现付来文留下的文档对于后来者是很有价值的，很容易了解到“如何部署服务器”、“如何运行服务器上的监控脚本”等等。终端的前任离开了，但Windows方面的工具等一些东西却是有遗失的。虽然有些东西用作测试等其它方面的使用，但它却是非常有价值的东西（可以用来分析问题，解决相应的问题，缩短调试的时间等）。

      记得当初第一份工作的时候，前东家的合同上有这么一句话（在为公司服务期间，所编写的代码和文档的所有权归公司所有），当时我笑了，我心想“系统已经如此的稳定，我们只是解解bug，会有什么东西留下，这是不是杞人忧天了”。然而，我幼稚的想法是非常错误的。除了平时解决bug，我们还是为公司开发了一些功能模块。公司强调着“所有权”的时候，它更侧重强调了“你要为公司留下什么”。一旦有人员流动时，借助着已有的文档，新的同仁就能够很快接手工作。虽然口头上的传授也是一种方法，但口口相传往往会产生一些谬误，也容易失去一些重要的东西。

     这让我想起了《笑傲江湖》的一个段子：“岳不群的师父传授给它几招《辟邪剑谱》，并嘱咐他‘这几招功夫华山派要代代相传’。岳不群看了之后，也认为那只是平 庸无奇的几招。见识了林平之耍的几招之后，觉得跟自己以前学习的那几招很相似，觉得林家的《辟邪剑谱》就是本门失传已久的武功绝学。自此以后，他就开始费 劲心思的去寻找那本书。当他得到的时候，他仅花费了不长的时间就学会了其中所有的武功”。在岳不群之前，华山派的那几招功夫传了好几代，却什么也没有悟出 来，究其原因缺的就是《辟邪剑谱》那本书。假设华山派没有失去那本武功秘籍，‘辟邪剑法’相信也能够跟‘紫霞神功’一样，代代相传。

     可见古语“好记性不如烂笔头”是值得让人深思的。何况一有变动的话，“好记性”已不在公司内部，成为了不可控因素。即便凭借以往的关系能够获取帮助，但他已 不存在为公司服务的义务，帮不帮完全在乎心情了。终端已尝试着整理一些文档，努力去阐明系统的架构。人可能往往看不清自己，所以这里暂且不论终端。只说说Windows客户端和测试，该两项在Wiki上的文档也是相对较少的。

     正如前面提到的，Windows方面的东西是有遗失的。目前，tuner模块的code是由Windows客户端方面维护的，至于“如何编译”、“如何烧写”、“如何更改mac地址和id”等等方面的文档是没有的。尽管只要花时间就能找到方法（这属于一种重复造轮子的行为，有文档的话，我们只要一步步操作即可），但已经会的东西我们又何必去浪费时间去研究呢？客户端的功能虽然已经完备，但也缺少文档的说明。虽然看code加上其他人员对系统的介绍，作为一个后来者也能够逐步接替该部分工作。但这就好比“岳不群不停地在那里耍大招，左冷禅在一旁观看（即便岳不群愿意这样做，左冷禅也未必能够学习到‘飞针’那一招）”那样，既费时，又不能体会其中真正的奥秘。

     很多人并不重视测试的作用，认为测试的工作有很多人可以替代。但我不以为然，一个好的测试人员描述的不仅仅是测试的表象，更多的会指出问题的根源，往往会起 到指导开发人员的作用。测试方面也很需要一些文档，而且这是很有必要的。虽然测试用例目前已经较完备，可谁来告诉后来者“如何设计同样有效的测试用例”、 “如何正确有效的提交bug（这 减少了开发和测试之间一些不必要的交互）”、“如何测试该系统”呢？我承认通过“开发者在某种意义上去指导后来的测试人员”来缩短学习时间。但我并不认为 这是一种有效、好的方法，开发者往往带有主观色彩，会告诉测试人员“你应该怎么做，不应该怎么做”，这往往会误导测试（按照开发讲的东西去测试，而未能发 现其中深藏的问题）。测试人员就应该专注于前辈留下的文档而脱离于开发者 ，站在客户的角度去思考问题。

     如今，需要做的并不一定是要完成某项任务，而是要一些有意义的文档。任务就好比是“鱼”，是目的；而文档就好比是“以渔”，是手段。现今公司要的是“以渔”（作为一个“受众者”是目前所能获取到的最大利益），避免未来重复的造轮子。

      虽然这只是一个建议，但还是诚恳的希望您能慎重的考虑一下它。文中难免有错误的出现，敬请谅解！