写在前面

为什么程序员不写文档？是不想写吗？最近，资深软件工程师 Kislay Verma 分析了背后的深层原因。

他认为软件工程师不写文档有以下两个主要原因。

#写作太难了

和所有人一样，软件工程师不写文档的原因是写作非常难。

写作本身是一件要求很高的任务，需要写作者将想法清晰地组织起来，进行批判性思考，最后再清楚表达出来。

在编程世界中，最佳答案等所有事情都基于一定程度的权衡，这也就使得写作更加困难。
程序员在写作时需要先说明背景，证明决策的正确性，再将低级思考引入代码。这类写作如果做好的话往往很有用，但想做好并非易事，甚至有时候仅仅完成写作就已经很困难了。
糟糕的代码还能运行，但糟糕的文档不会。

这就是许多人针对代码注释的价值和自文档化代码（self-documenting code）展开争论的原因。
《程序员应该知道的 97 件事》的作者 Kevlin Henney 曾说，为复杂代码添加注释是徒劳的，用代码里都无法表达清楚，怎么可能用文字表达清楚呢？

不写文档不影响开发进程

开发者不写文档，并不耽误工作进程，起码不会立刻带来什么负面影响。而事实上，不将技术决策文档化带来的影响是一直在累积的。

写作是一件关乎思考和分析的事。大多数情况下，写代码可以摸着石头过河。组织结构欠佳的代码或许也能运行，但胡乱堆砌的文字和段落很难让人读懂。
写作必须清晰，才能有用。而代码只要能够运行就可以（一定程度上）被接受。由于大部分组织只关注如何使产品推进，于是那些不会影响开发进程的事情就理所当然被忽略了。

在很多团队中，单元测试也面临类似的问题。要想测试代码，我们需要首先理解它，但这要比写代码费工夫多了，而且不做单元测试也不影响工作进程。于是，很多团队不重视对代码做单元测试。

还有一个问题：过时。即使优秀的文档也会过时，因此工程师在构建系统时，必须不断地重复「思考 - 分析 - 表达」这一过程。

总之，放弃写文档太容易了。

工欲善其事，必先利其器

毫无疑问，目前用于文档撰写的工具并不足够。我们并不以文档的角度思考问题，而是从 idea 和目标的角度考虑，一次性拼凑好几个概念。
文档是思考过程的反映，这样形成的文档质量就可想而知了。我们需要一些工具，帮助我们梳理不同时间的想法，进而解决手边的问题。
对于这类写作而言，Google Docs、Confluence、Markdown 并不足够。

不过，新一代工具（如 Notion、Roam）正在解决「网络化思想」的问题。这些工具有助于将思考转化为文档。

但是，缺少工具绝非不写作的借口。工具当然有用，但是否具备写作意愿才是问题的关键。