FAQ

不写文档的原因很多很复杂，有合理的，也有不合理的，有主观原因，也有客观原因，待我述来。

诸如 MS、Oracle、IBM 之类的一流大厂的软件开发文档写得怎么样，大家有目共睹，不用我赘述。

三流组织是指那些连管理层的基本诚信都有问题的企业或团队，组织的文化、管理与技术基本上是可以用“烂”字来形容的（可能个别的技术还不错），所以普遍的是没有文档，即使有的话也极难读。如果您不幸落入了三流团队，不写文档（以免給自己的利益带来损害），我当然是举双手赞成的，不但尽量不要写、少写，而且要赶紧跑，跳出坑。

麻烦的是二流组织。根据以上分布模型，江湖上最多的其实是中不溜秋的二流组织，文化、管理与技术都处于中游水平。我们重点来谈谈二流组织。

一般二流团队的领导与员工都知道软件工程管理与开发文档的重要性，但由于内部文化、管理、技术上的一些欠缺，加上外部市场（与一流企业）的竞争压力，导致软件工程与研发管理的整体水平不高，开发文档的质量管理上或多或少都存在着一些问题。

常见的不写（或忽视）文档的原因，我归纳主要有以下几点：

1. 不知道怎么写，写不好；
2. 嫌写文档、更新文档麻烦；
3. 以为代码+注释完全可以取代文档；
4. 团队的软件工程管理水平差，成熟度低；
5. 团队的氛围差，用心写文档不仅吃力不讨好，还有损个人利益；
6. 受到近十几年来敏捷运动中某些极端思想的影响；
7. 无脑跟风与装 X；
8. 不写或少写文档是某些知名开源软件的商业补贴模式；
9. 初创小团队代码优先，开发文档的优先级不高；
10. 当前开发的产品与代码确实很简单，大家都懂，没必要写文档；
11. ...

不写或少写文档的合理原因

原因 9 许多初创团队不写文档或文档少，这是合理的，因为都赶着要尽快正式发布一个初始产品以争取市场份额与关注度，而在产品需求、架构都还很不稳定的情况下，如果要在代码+注释之外再拿出详细的开发文档，确实时间与精力都不够。

与原因 5 相似，楼里佚名也提到：

还有就是个人写并不代表团队写.很多时候有些东西写出来自己和公司的制衡也就丢失了不少....

他说出了很重要的一点。二流企业团队中这种情况是比较突出（大家心照不宣）的：个人与团队、公司之间存在的一种微妙的博弈（制衡）关系。

你用心把文档写好了，让大家都迅速看懂了，领导、同事、用户都很满意，真的、必然对自己有好处和好报吗？不一定吧。

在一些不太有利的商业环境下，出于个人职业保护的目的，不写、少写文档或者把文档写得模糊、晦涩一点，让想了解的人自己去看复杂的源码而不是立马就明白了，这我是赞成的，尤其是某些二乙、二丙团队。

为啥许多知名开源软件文档少？

原因 8，许多知名开源软件表面上看着都是代码，独立的文档少，还有一个潜藏的原因（设计）：

你想尽快看懂的话，让你去买作者们写的书（付书费），参加各种技术大会与培训（付报名费、会议费和培训费），最好再找作者咨询（付咨询费），这其实是一种比较流行的开源商业（赚钱或补贴）模式。

当然，也可以把这些详细解读的书看作文档，只不过要付费获得。如果采用这种模式，当然是免费的文档越少越好。

。。。