文档难

项目开发过程中，编写文档是非常有必要的。正如在上一篇文章漫话文档|究竟为何要写文档？中所讨论的那样。然而，正如大家所看到的，即使很多团队反复强调文档的重要性，团队在推行文档落实的路上，仍然走的十分艰难。

落实文档的路上，我们到底遇到了哪些拦路虎呢？这篇文章，给大家分享下我个人的经验与看法，也希望能抛砖引玉，大家积极交流，也希望多提宝贵意见。

缺乏严谨的工匠精神

这个原因，主要来自于我个人的经验总结。因为，即时到了现在，偶尔我还会被这个原因击败，无法沉下心来去写文档。

具体来讲：就是我们在进行系统设计时，不愿意去写文档，是因为我们根本不了解我们的系统。我们只是拍脑门，觉得这个主意不错。至于系统真正的内部结构，我们并没有细致的设计与分析。面对这样一个外部清晰，内部混沌的系统，用一个文档把它彻底说清楚，确实是非常困难的。与其说是写文档，不如说是在做系统架构，甚至是系统细节设计。

面对这样一个需要严谨分析，小心设计的工作，如果我们稍微没有耐心，没有足够的工匠精神，那么很可能“拖延症”就会强势介入。并且一大堆的理由也会迎面而来：“代码写好了就行”，“哎呀，先写代码吧，文档后面再补”。这个时候，如果是在一个文档氛围不够浓厚，或者研发管理不太成熟的团队中，这个坏坏的小想法，就很容易得逞。

基础薄弱，能力欠佳

文档是一个技术活，并不是谁想写就能写好的。

上面说了，编写文档的工作实质是在做系统设计，而系统设计，往往需要设计人员具备很强的技术功底。

假如说目前要根据实际需求，实现一个搜索功能，我是否能够迅速的说出常见的排序算法的时间和空间复杂度以及排序稳定性？或者说我们要做一个数据库设计，我是否可以讲清楚第一范式，第二范式等范式的区别？在做系统结构设计时，我是否清楚常见的设计模式，以及他们的优缺点，甚至基于现在的实际情况，提出更好的改良过的设计模式？

没有这些扎实的理论基础，就不可能做好方案论证，做不出优秀的产品设计，更不具备写好文档的基本条件。

文档比代码更容易失效

代码是一个无比精确的工作成果。只要时间足够久，里面的错误总会被暴露出来。而文档确不是这样。文档经常会面临因维护不及时而失效的问题。有人就说过，文档从它被写出的那一刻起，就已经开始失效。

所以，面对如此一个残忍的现实，如果大家赶着交付，时间有限。那我宁愿把更多的时间投入到编码工作中去，而不是文档编写工作中去。

这个问题，不但工程师有时会这么想，常常有项目经理也会这样想。然而，这样做往往是把交付时间提到了前面，却把位置的隐患埋到了后方。

大批劣质文档降低了对文档的认同感

我们不得不不承认，我们周围有很多劣质的文档：

• 排版质量很差，不便于阅读；
• 文档结构松散，引用关系不清晰甚至错误；
• 文档内容与其他文档内容相似，信息冗余，意义不大；
• 细节，前后逻辑，因果关系交代不清晰或者错误；

除了以上所列出的，还有很多其他原因，导致“文档无用论”暂时占据制高点，从而影响文档落实工作。

文档更容易暴漏设计人员的无知

不好意思。我可能说出了许多人不愿意说出，甚至不愿意承认的话。上面已经提到，写文档，需要非常扎实的技术实力。如果在这方面比较欠缺的话，只要你的文档一出，你所有的欠缺，都会立马暴露无疑。

我害怕别人看出我不行，害怕领导清楚了我的能力，不给我晋升的机会。我需要维护我在团队中的权威形象……

如果真是这个原因，成为了我们自身的拦路虎。那我们真的有必要好好调整下心态。团队的胜利不能靠个人英雄主义；个人要想进步，也要先正视自己的不足。

不成熟的工作观

“按照领导要求，按时完成工作任务”仅仅是最基本的工作要求。任正非曾经说过：要阅读指令，并理解指令，而不是机械的执行指令。我们完成工作，可以拿到薪水，但是我们的工作不能仅仅是为了拿到薪水。我们的每一项工作，都会产生工作成果。我们不仅要产生成果，还要尽可能的保证这个成果能够更便利的被他人享用，也能被更多的人享用，从而产生更高的价值。

基于这样的角度出发，请问，我们怎能允许一段代码没有任何文档、注释，就被交付至同事的手中？

话已至此

阻挡自己不断进步的最大敌人，其实是自己。编写优秀的文档，交付优秀的产品，共勉！