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

[[122442]]

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

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

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

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

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

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

2.不提供在線文檔

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

3.只有在線文檔

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

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

4.不包含安裝文檔

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

5.缺乏截圖

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

6.缺乏實(shí)例

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

7.不充分的鏈接和引用

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

8.忘記新用戶

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

9.不傾聽用戶需求

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

10.不接受用戶輸入

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