程序员写文档

提到写文档，你的反应是什么

写文档，本来在码农眼中就不是什么分内之事。真要到了赶鸭子上架的份上，码农的各种不良反应也都来了，有的人心慌、没底；有的人心不甘、情不愿；也有的人浑身发怵心有余悸。
不同的不良反应都折射出各色码农对于写文档的态度。

• 心慌没底的应该是没有写过文档，在偌大的一张A4纸或是一页word文档上，他们能够发呆老半天，就是无从下笔，不止从何写起。他们很难有层次的、有重点的让别人明白文档想要传达的意图，也有可能他们自己也不知道要传达什么。

  
  

• 心不甘情不愿的多多少少会有点文档无用论的想法，认为文档没什么用。遇到需求来了，就开始拿起键盘，一通复制粘贴，洋洋洒洒的就可以码起了自己的项目，又何须多一道写文档这种“中看不中用”的手续。

  
  

• 浑身发怵心有余悸的应该是写过文旦并且在文档上栽过跟头的，他们认识到文档的重要性和作用，但是因为文档没有写好，比如疏漏了某个点最终导致开发偏离正轨，这样的经历和惨痛教训仍历历在目。

  
  

最近自己写一个小项目的开发文档过程中遇到不少问题，也从老大那边学到了不少经验，所以在此总结下。

---

写文档，我们会遇到什么问题

作为码农，毫无疑问，我们的第一使命就是扑上前线写代码，我们常常沉浸在自己的技术世界中无法自拔。一个问题，一个需求出来，我们本能的在脑海中闪过出各种算法、各种设计模式、各种架构，设想了各种让人眼花缭乱的技术解决方案。但是，我们很少从另外一个角度来看待问题以及解决问题——业务角度。我们很少问自己为什么会出这个bug，我们从业务上有没有必要这么做，当初的设计是否考虑周全？

文档的重要性，其实大家应该都很清楚。一份好的文档，可以大大减少沟通成本，开发成本，尤其在项目涉及到多个项目组合作的时候，有一个标准文档显得格外重要。同时，有了文档，也方便日后的同事快速熟悉业务。文档固然重要，但是写起来并不简单！我们很容易遇到这些问题：

• 思维定式
  长时间奋斗在一线的我们在写起文档时容易思维定式，条件反射的从技术实现角度来考虑问题，容易钻牛角尖。最终写出来的文档可能因为技术性太强，所以一起参与开发的其他组或者非技术人员会就很难读懂。

  
  

• 格局小
  因为我们对于自己相关负责的模块会比较熟悉清晰，自然写的比较详细。而对于其他项目组以及相关人员的工作职责不清楚，就写的比较模糊。后面别人看文档时因为疑问较多，需要反复的沟通确认，这样就增加了时间和人力的成本。或者别人索性也不问，直接在模糊的文档基础上加入自己的理解，这样就可能误解了原来的设计需求，导致做了一些无用的开发，间接导致项目延期。

  
  

所以，我们应该走出自己的一亩三分地，走出自己的小天地，站在一个高点，有一个全局观。从全局角度，让整个设计方案在理论上和实际沟通后确实可行。对于每个部分，尤其是各项目组或者各部门的衔接部分要反复确认，减少后期不必要的对接成本。具体，我们可以从下面一些点着手。

---

为了写好文档，我们该怎么做开会不是走形式

大部分人对开会都没有什么好感，我们参加过太多又臭又长而又漫无目的的会议，这些形式主义的会议耗去了我们太多的精力和耐心。但是，不可否认，会议本身没有错，只是有些人没有用对而已。
当然有些问题和议案我们大可不必通过会议的形式来讨论解决，我们可以直接找到相关的人来一场face to face的高效沟通。但是会议本身有一些不可替代的好处：

• 集思广益
  因为有些项目需要很多人、多个项目组参与开发，对于一个需求，某个人的了解比较片面，通过会议的形式，大家都能出谋划策，利用自己的技术和业务背景知识献计献策，让文档、方案考虑更加周全。

  
  

• 仪式感
  就像老大说的，通过会议的形式营造出一种仪式感。大家通过一个很正式的会议形式明确自己的职责并对要做的工作做好安排，这无形中增加了大家各自心中的责任感。

  
  

基于此，会议有其必要性。在开会这件事上，我们还有几个注意的点。

• 开会前，先知会需要参会的人员，确保大家都能就位。

  
  

• 开会前，提纲挈领的列出此次开会着重要讨论的问题，针对问题来开会，提供开会的效率。如果在开会的时候才想着要讨论的问题，就会目的性不强，可能聊着聊着就跑偏了。

  
  

• 做好会议摘要，针对会议中提到的问题以及解决方案，简要记录，会后整理到文档中。

  
  

• 开会时，自己的立场要坚定，对于明确确定的要求不能动摇或者模棱两可。当然，这不是说要在开会偏执己见，不管别人说的对与错都不辨是非还固守自己的观点。

  
  

积极推动、及时跟进

• 对于牵头项目的人在跳脱自己一亩三分地的思想之外，我们还应该保持积极推动和跟进的热情。

  
  

• 对于一些模糊的点需要找相应的人反复确认，对于大家有歧义的地方不要支支吾吾，敷衍了事，因为这样很有可能就会偏离设计需求的初衷。

  
  

• 作为码农，一般喜欢跟代码打交道，不大愿意也不太擅长于人沟通打交道，但是为了明确自己做的或有意义，我们需要积极主动的沟通。因为花点时间沟通明确了问题和需求，要好过我们因为没有弄懂需求而反复修改代码，最后让自己疲惫又被动。

  
  

• 对于设计文档的整个逻辑要清楚，先保证设计能通，然后在每个部分考虑具体细节，不要只相信某一个人的说法。比如A说不需要B的参与我们就能搞定问题，但是等最终做完发现，因为没有B的参与，系统根本不可能用。我们需要自己想清楚，并找可能与之有关的人员核实清楚。

  
  

写文档并不那么简单，看似单薄的几页文档需要我们有严密的逻辑，能够协调和把控各个环节，跟踪和调整项目的进度，只有这样才能体现文档的重要性并发挥它的价值。

123123

456456