码农不重视文档:开源项目深受其苦

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

码农不重视文档:开源项目深受其苦的照片 - 1

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

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

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

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

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

码农不重视文档:开源项目深受其苦的照片 - 2

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

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

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

[编译自:TNW , 来源:GitHub]

weinxin
N软网微信公众号扫一扫
观点新鲜独到,有料有趣,有互动、有情怀、有福利!关注科技,关注N软,让我们生活更加美好!

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: