大多數(shù)開(kāi)源開(kāi)發(fā)人員喜歡思考他們構(gòu)建軟件的質(zhì)量，但其文檔的質(zhì)量常常被遺忘。沒(méi)有人談?wù)撘粋€(gè)項(xiàng)目的文檔是多么出色，但其實(shí)文檔對(duì)一個(gè)項(xiàng)目的成功卻有直接的影響。沒(méi)有一個(gè)良好的文檔可能用戶根本不會(huì)使用你的項(xiàng)目，亦或者壓根不會(huì)喜歡。

[[122442]]

然而大多數(shù)開(kāi)源項(xiàng)目的文檔都是令人極其失望的，主要從以下的幾個(gè)方面來(lái)體現(xiàn)。

1.缺乏一個(gè)好的自述或介紹

自述是潛在用戶對(duì)你項(xiàng)目的***印象。如果項(xiàng)目在GitHub上，自述自動(dòng)的顯示在該項(xiàng)目的主頁(yè)上。如果你稍微不留神將自述弄錯(cuò)了，這些潛在的用戶有可能再也不會(huì)回來(lái)了。所以你的項(xiàng)目必須有一個(gè)好的自述來(lái)吸引用戶對(duì)你的項(xiàng)目產(chǎn)生興趣。

自述文件至少應(yīng)該包括以下幾點(diǎn)說(shuō)明：

• 是什么項(xiàng)目
• 面向何種用戶
• 運(yùn)行在什么硬件或者平臺(tái)上
• 主要依賴關(guān)系
• 如何安裝或者深入的方向指針

這些都是寫給那些之前從未聽(tīng)說(shuō)過(guò)你的項(xiàng)目甚至可能永遠(yuǎn)不會(huì)考慮你的項(xiàng)目的用戶。當(dāng)然也不要以為每個(gè)閱讀你自述的用戶都知道那是什么，必要的時(shí)候需要做出一些注解以及附上一些有用的鏈接，方便用戶了解你的項(xiàng)目。

2.不提供在線文檔

雖然沒(méi)有看到過(guò)關(guān)于這方面的研究調(diào)查，但我想90%的文檔都是通過(guò)谷歌或者互聯(lián)網(wǎng)的其他瀏覽器來(lái)查找的。所以文檔必須在線并且可用。這一點(diǎn)我是如何發(fā)現(xiàn)的呢？因?yàn)楹芏嗟挠脩舫３?huì)不看常見(jiàn)問(wèn)題的解答，而直接從網(wǎng)上搜索問(wèn)題的答案，這常常就會(huì)在項(xiàng)目中出現(xiàn)問(wèn)題。因此提供在線的文檔可以幫助用戶更好的解決問(wèn)題。

3.只有在線文檔

這個(gè)問(wèn)題的另一面就是開(kāi)發(fā)人員只提供在線的文檔。有些項(xiàng)目不附帶該項(xiàng)目可交互的文檔，或者包含的文檔是不符合的版本。例如PHP語(yǔ)言不附帶任何文檔，如果你想要文檔，必須用一個(gè)單獨(dú)的頁(yè)面來(lái)打開(kāi)他們。然而更糟糕的是，只有核心代碼可以下載。這樣導(dǎo)致用戶可能不能獲得對(duì)自己有用的信息。

開(kāi)源項(xiàng)目不能想當(dāng)然的認(rèn)為用戶訪問(wèn)互聯(lián)網(wǎng)時(shí)他們需要在線的文檔。當(dāng)然你也不希望用戶過(guò)分的依賴你的項(xiàng)目網(wǎng)站。

4.不包含安裝文檔

這個(gè)問(wèn)題通常是包的創(chuàng)造者而不是項(xiàng)目開(kāi)發(fā)者的問(wèn)題。例如在Ubuntu Linux操作系統(tǒng)中，Perl語(yǔ)言選擇的包本身是一個(gè)單獨(dú)的文檔。用戶必須知道他在安裝的時(shí)候所需要的安裝文檔以及核心語(yǔ)言的文檔，這樣方便用戶在遇見(jiàn)問(wèn)題時(shí)及時(shí)地解決。

5.缺乏截圖

有沒(méi)有更好的方式來(lái)獲取潛在用戶的注意，或者說(shuō)明軟件的正確使用方法？比較明智的做法是截圖。在互聯(lián)網(wǎng)時(shí)代，一張圖也許勝過(guò)千言萬(wàn)語(yǔ)。截圖能讓用戶判斷自己使用的方法是否正確，也容易讓他找到自己出錯(cuò)的地方。因此必要的截圖對(duì)于開(kāi)源文檔來(lái)講也是至關(guān)重要的。

6.缺乏實(shí)例

對(duì)于基于代碼的項(xiàng)目，模擬的截圖固然是非常不錯(cuò)的，但是相關(guān)的實(shí)例也是必不可少的。這些實(shí)例不應(yīng)該是抽象的，而應(yīng)該是從現(xiàn)實(shí)世界當(dāng)中提取的。花時(shí)間創(chuàng)建一些與項(xiàng)目相關(guān)的實(shí)例，向用戶展示如何解決軟件使用過(guò)程中出現(xiàn)的問(wèn)題。

7.不充分的鏈接和引用

如果有超鏈接，記得在文檔中使用它們。不要以為用戶讀完文檔就能明白并且理解，文檔當(dāng)中可能會(huì)存在一部分用戶并不能理解的東西。這時(shí)候就需要你使用你所有的超鏈接以及引用來(lái)幫助用戶解決一些問(wèn)題。

8.忘記新用戶

當(dāng)你寫文檔時(shí)，你是站在開(kāi)發(fā)者自己的角度上來(lái)編寫的，這對(duì)于軟件的開(kāi)發(fā)者來(lái)說(shuō)著很容易。然而對(duì)于那些新用戶來(lái)講，則需要入門文檔。為了使新用戶能夠盡早的了解你的軟件或者說(shuō)熟練掌握使用軟件的方法，我認(rèn)為應(yīng)該使用單獨(dú)的頁(yè)面來(lái)為用戶書寫入門文檔。

9.不傾聽(tīng)用戶需求

項(xiàng)目的開(kāi)發(fā)者必須傾聽(tīng)用戶對(duì)整個(gè)項(xiàng)目的需求。最有效的方法就是讓更多的人對(duì)你的項(xiàng)目進(jìn)行試用來(lái)找出問(wèn)題。同等重要的是，在傾聽(tīng)用戶需求的過(guò)程當(dāng)中，項(xiàng)目開(kāi)發(fā)人員應(yīng)該考慮到用戶提出這些問(wèn)題背后的真正原因。

10.不接受用戶輸入

如果你的項(xiàng)目有一個(gè)足夠大的用戶群，你可以讓用戶直接將評(píng)論添加到文檔當(dāng)中。我見(jiàn)過(guò)的***的例子是PHP語(yǔ)言，其文檔中的每個(gè)頁(yè)面允許經(jīng)過(guò)身份驗(yàn)證的用戶添加評(píng)論，或添加的評(píng)論不屬于核心文檔。