GitHub 剛剛發(fā)布了《2017 開源調(diào)查》報(bào)告，這家知名編程社交網(wǎng)站走訪了 github.com 社區(qū)內(nèi) 3800 多個(gè)項(xiàng)目和超過 5500 名成員，并且與 500 名在 GitHub 項(xiàng)目生態(tài)系統(tǒng)之外的編程者們進(jìn)行了交談。本次調(diào)查涉及多方面，比如人們?cè)跒殚_源項(xiàng)目做開發(fā)、做貢獻(xiàn)時(shí)遇到的問題，結(jié)果有 93% 的人對(duì)“不完整或令人困惑的文檔”感到非常沮喪。

然而這沒能出乎我們的意料，因?yàn)?GitHub 上確實(shí)有許多描述很稀疏的項(xiàng)目，缺乏如何去使用它們的知道。如果你的腦實(shí)力不夠強(qiáng)大，肯定會(huì)獨(dú)自栽在這上面。

很遺憾，很多碼農(nóng)忽視了文檔對(duì)一個(gè)項(xiàng)目取得成功的重要性。科技作者 Mike Pope 曾經(jīng)如此總結(jié)文檔的需求：

我們需要告訴開發(fā)者，‘缺了文檔，就等于廢了項(xiàng)目’！（If it isn’t documented, it doesn’t exist.）

你不僅必須寫文檔，還得在其中好好解釋、教導(dǎo)和示范。這樣的話，大家都會(huì)很高興的。這不僅關(guān)乎你的文檔，也關(guān)乎你的產(chǎn)品！

此外，Stack Overflow 創(chuàng)始人?Jeff Attwood、以及 JavaScript 開發(fā)者 Nicholas Zakas，也都在博文中強(qiáng)調(diào)過文檔的重要性。

GitHub《2017 開源調(diào)查》中排名靠前的幾個(gè)問題，在“文檔不完整或困惑”之后，分別是“不回應(yīng)”、“不屑”、“沖突”、“不明原因的拒絕”、以及“不歡迎的語言或內(nèi)容”。

GitHub 在調(diào)查中強(qiáng)調(diào)：“文檔有助于營造一個(gè)包容性的社區(qū)，清楚地解釋了一個(gè)項(xiàng)目的過程，比如貢獻(xiàn)指南和行為準(zhǔn)則，大家會(huì)很珍視這樣的開源工作、但它往往被低估”。

調(diào)查還指出，高達(dá) 60% 的貢獻(xiàn)者很少或從未對(duì)文檔提供過幫助。

原文地址：http://www.cnbeta.com/articles/soft/618585.htm

---

.NET社區(qū)新聞，深度好文，微信中搜索dotNET跨平臺(tái)或掃描二維碼關(guān)注

總結(jié)

以上是生活随笔為你收集整理的码农不重视文档：开源项目深受其苦的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。