GitHub 刚刚发布了《2017 开源调查》报告，这家知名编程社交网站走访了 github.com 社区内 3800 多个项目和超过 5500 名成员，并且与 500 名在 GitHub 项目生态系统之外的编程者们进行了交谈。本次调查涉及多方面，比如人们在为开源项目做开发、做贡献时遇到的问题，结果有 93% 的人对“不完整或令人困惑的文档”感到非常沮丧。

然而这没能出乎我们的意料，因为 GitHub 上确实有许多描述很稀疏的项目，缺乏如何去使用它们的知道。如果你的脑实力不够强大，肯定会独自栽在这上面。

很遗憾，很多码农忽视了文档对一个项目取得成功的重要性。科技作者 Mike Pope 曾经如此总结文档的需求：

我们需要告诉开发者，‘缺了文档，就等于废了项目’！（If it isn’t documented, it doesn’t exist.）

你不仅必须写文档，还得在其中好好解释、教导和示范。这样的话，大家都会很高兴的。这不仅关乎你的文档，也关乎你的产品！

此外，Stack Overflow 创始人 Jeff Attwood、以及 JavaScript 开发者 Nicholas Zakas，也都在博文中强调过文档的重要性。

GitHub《2017 开源调查》中排名靠前的几个问题，在“文档不完整或困惑”之后，分别是“不回应”、“不屑”、“冲突”、“不明原因的拒绝”、以及“不欢迎的语言或内容”。

GitHub 在调查中强调：“文档有助于营造一个包容性的社区，清楚地解释了一个项目的过程，比如贡献指南和行为准则，大家会很珍视这样的开源工作、但它往往被低估”。

调查还指出，高达 60% 的贡献者很少或从未对文档提供过帮助。

原文地址：http://www.cnbeta.com/articles/soft/618585.htm
.NET社区新闻，深度好文，微信中搜索dotNET跨平台或扫描二维码关注