共计 1339 个字符，预计需要花费 4 分钟才能阅读完成。
为什么程序员不写文档？是不想写吗？最近，资深软件工程师 Kislay Verma 剖析了背地的深层起因。
他认为软件工程师不写文档有以下两个次要起因。
写作太难了
和所有人一样，软件工程师不写文档的起因是写作十分难。
写作自身是一件要求很高的工作，须要写作者将想法清晰地组织起来，进行批判性思考，最初再分明表达出来。
在编程世界中，最佳答案等所有事件都基于肯定水平的衡量，这也就使得写作更加艰难。程序员在写作时须要先阐明背景，证实决策的正确性，再将低级思考引入代码。这类写作如果做好的话往往很有用，但想做好并非易事，甚至有时候仅仅实现写作就曾经很艰难了。蹩脚的代码还能运行，但蹩脚的文档不会。
这就是许多人针对代码正文的价值和自文档化代码（self-documenting code）开展争执的起因。《程序员应该晓得的 97 件事》的作者 Kevlin Henney 曾说，为简单代码增加正文是徒劳的，用代码里都无奈表白分明，怎么可能用文字表白分明呢？
不写文档不影响开发过程
开发者不写文档，并不耽搁工作过程，起码不会立即带来什么负面影响。而事实上，不将技术决策文档化带来的影响是始终在累积的。
写作是一件关乎思考和剖析的事。大多数状况下，写代码能够摸着石头过河。组织构造欠佳的代码或者也能运行，但胡乱堆砌的文字和段落很难让人读懂。写作必须清晰，能力有用。而代码只有可能运行就能够（肯定水平上）被承受。因为大部分组织只关注如何使产品推动，于是那些不会影响开发过程的事件就天经地义被忽略了。
在很多团队中，单元测试也面临相似的问题。要想测试代码，咱们须要首先了解它，但这要比写代码费工夫多了，而且不做单元测试也不影响工作过程。于是，很多团队不器重对代码做单元测试。
还有一个问题：过期。即便优良的文档也会过期，因而工程师在构建零碎时，必须一直地反复「思考 – 剖析 – 表白」这一过程。
总之，放弃写文档太容易了。
工欲善其事，必先利其器
毫无疑问，目前用于文档撰写的工具并不足够。咱们并不以文档的角度思考问题，而是从 idea 和指标的角度思考，一次性拼凑好几个概念。文档是思考过程的反映，这样造成的文档品质就可想而知了。咱们须要一些工具，帮忙咱们梳理不同工夫的想法，进而解决手边的问题。对于这类写作而言，Google Docs、Confluence、Markdown 并不足够。
不过，新一代工具（如 Notion、Roam）正在解决「网络化思维」的问题。这些工具有助于将思考转化为文档。
然而，短少工具绝非不写作的借口。工具当然有用，但是否具备写作志愿才是问题的要害。
如何撰写文档？
Kislay Verma 示意：「写软件教会了我一件事。想要用户做某件事，你必须使这件事成为应用产品过程中必不可少的一步。」写作也是如此。将文档作为代码的装点不会见效，甚至是无用的。
写作关乎批判性思考，须要你向本人和读者解释思考过程和用意。 思考过程为文档 / 写作减少了价值，而不只是动态地记录曾经实现的代码。
Mob 编程 / 成对编程和极限编程的支持者通常看轻文档写作。但除了那些类型之外，写作和 review 技术文档是团队独特了解本人所创立产品的惟一形式，这对团队和代码库的长期衰弱倒退十分要害。
原文链接：https://kislayverma.com/progr…