为什么很多知名开源框架的文档只有 API 文档，没有系统设计文档？

[changwei]

现在很多知名开源项目，只开放 API Manual 的话，只是方便使用者把它当做一个黑盒子来使用。

但是想鼓励大家学习开源项目里面的设计思想，或者鼓励更多人去为开源项目做贡献，应该还要有相关的系统设计文档，包括 UML 图，如果有数据库，那么还得有 E-R 实体关系图，数据字典等等。

然而我发现现在很多知名开源项目都缺少这些关键性的系统设计文档。一些稍微简单的偏商业化的开源项目甚至只有一个安装部署文档，其他什么都没有。我觉得这个和开源的精神有点不太契合。因为开放源代码的意义并不不仅仅是说免费（事实上很多商业化的开源项目也不是完全免费，而是以收取授权费的形式运作），而是希望源代码让大家能够读懂看懂，接受大家对软件质量和信息安全的监督和 review 。

如果一个软件的代码只是放出来，但是缺乏一定的系统设计文档，那么大家读懂它以及对它进行 review 的成本就会过大，这样的话开源的意义就没有凸显出来。就像知乎上也有很多人说自己不用开源项目或者一些重型开源框架的原因就是：开源项目的代码量太大，太难读懂，学习成本太大，对于一些细节没办法完全把控，有读懂开源项目的时间还不如自己造一个轮子。因此缺乏系统设计文档也导致了“重复造轮子”的现象频繁发生。

即使是框架的用户，如果能有相关的文档或者架构图，能够一眼就看出整个项目的注册部分，那么在开发中也会更加放心安心，至少遇到一些框架内部的报错，大概也能快速定位错误原因，方便给作者提 issue 甚至是自己就可以小修小改解决框架内部的 bug 。这样对于一个开源项目的良性运作是非常有益的。

（ PS：我并没有指责那些开源项目不好，那些 contributors 都非常厉害非常值得敬佩，我只是提一个小小的美中不足的意见，希望能够让开源项目发展更好。因为楼主最近自己在研读某知名开源项目的源代码就意识到了这个问题，如果我有一天读懂了，我当然愿意去为这个项目贡献相关的系统设计文档。）

[fixend]

程序员都不爱写文档。。。

[cabing]

能开源就不错了。哪有时间写文档。

而且，做出东西后，就觉得这东西不难，应该能看懂吧的错觉。写啥文档。

[iamwho]

古诗作者也应该附言一份写作时的思想感情。

[lower]

感觉还是看项目类型吧，
有的项目的定位就是工具或库，就是让你直接用，就没有；
有的是那种集成框架平台的，需要在它上面二次开发修改的，就会有架构图、依赖的相关工具服务都会有。
更有超大项目的话，会有人专门写书来介绍的😀

[zhs227]

大部分的项目都不是一开始设计出来的，都是无数的 Feature Request 讨论出来的。
你关注一个开源项目时间长一点，仔细的看一下 changelog，尤其是 PR
写一个文档可能没多久就会过时，很多人就不会愿意写这些内容

[huaouo]

书 http://www.aosabook.org/en/

[seki]

因为没有明显的收益

写这些东西花费的精力可能比实际开发时间还要多，然而：
这些东西读完需要花别人多少时间呢？
维护需要消耗多少额外的工作量呢？
做了这些能吸引到多少人参与进来呢？
贡献者都只是从修复一小部分开始的，有多少人真正需要看这些内容呢？

反过来，就算没有这些文档，如果有很好的代码组织结构，很丰富的注释，很完善的测试用例，也不比这一个专门文档差了

[MrKou47]

呃..我理解开源的项目，应该向外暴露的东西都应该是最关键的东西，也就是从使用者的角度出发来编写文档，demo 这种。具体架构设计方面，应该会有 blog，或者 youtube 的视频来做这方面的解释