請別只看重開源方案質素！「說明文件」的好與壞隨時影響使用人數

大多數開放原始碼的開發人員喜歡思考他們構建軟件的質量，但其文檔的質量常常被遺忘。沒有人談論一個項目的文檔是多麼出色，但其實文檔對一個項目的成功卻有直接的影響。沒有一個良好的文檔可能令用戶根
本不會使用你的項目，然而大多數開放原始碼項目的文檔都是令人極其失望；綜合筆者多年來對開源方案的心得，以下分享一些見解，有錯請指正。

1.缺乏一個好的自我介紹

自我介紹是潛在用戶對你項目的第一印象。如果項目在GitHub上，自我介紹自動的顯示在該項目的主頁上。如果你稍一不留神「搞大了」，這些潛在的用戶有可能再也不會回來了。所以你的項目必須有一個好的介紹來吸引用戶對你的項目產生興趣。

自我介紹文件至少應該包括以下幾點：

– 是什麼項目；
– 面向何種用戶；
– 運行在什麼硬件或者平台上；
– 主要依賴關係
– 如何安裝或者深入的方向指南。

這些都是寫給那些之前從未聽說過你的項目甚至可能永遠不會考慮你的項目的用戶。當然也不要以為每個閱讀你介紹的用戶都知道那是什麼，必要的時候需要作些注解以及附上一些有用的超連結，方便用戶了解你的項目。

2.不提供在線文檔

雖然沒有看到過關於這方面的研究調查，但我想90%的文檔都是通過Google或者互聯網的其他瀏覽器來查找的。所以文檔必須在線並且可用。這一點我是如何發現的呢?因為很多用戶常常會不看常見問題的解答，而直接從網上搜尋問題的答案，這常常就會在項目中出現問題。因此提供在線的文檔可以幫助用戶更好的解決問題。

3.只有在線文檔

這個問題的另一面就是開發人員只提供在線的文檔。有些項目不附帶可互動的文檔，或者包含的文檔是舊版本。例如PHP語言不附帶任何文檔，如果你想要文檔，必須用一個單獨的頁面來打開他們。然而更糟糕的是，只有核心代碼可以下載。這樣導致用戶可能不能獲得對自己有用的信息。開放原始碼的項目不能百分百代表用戶瀏覽互聯網時一定需要在線的文檔。當然你也不希望用戶過分的依賴你的項目網站。

4.沒有安裝文檔

這個問題通常是安裝包的開發者而不是項目開發者的問題。例如在Ubuntu Linux操作系統中，Perl語言選擇的安裝包本身是一個單獨的文檔。用戶必須知道他在安裝的時候所需要的安裝文檔以及核心語言的文檔，這樣方便用戶在遇見問題時及時地解決。

5.缺乏截圖

有沒有更好的方式來獲取潛在用戶的注意，或者說明軟件的正確使用方法。比較明智的做法是截圖。在互聯網時代，一張圖也許勝過千言萬語。截圖能讓用戶判斷自己使用的方法是否正確，也容易讓他找到自己出錯的地方。因此必要的截圖對於開放原始碼的文檔來說也是最重要的。

6.缺乏實例

對於基於代碼的項目，擁有截圖固然是非常不錯的，但是相關的實例也是必不可少。這些實例不應該是抽象的，而應該是從現實世界當中獲取的。花時間創建一些與項目相關的實例，向用戶展示如何解決軟件使用過程中出現的問題。

7.不充分的超連結和引用

如果有超連結，記得在文檔中使用它們。不要以為用戶讀完文檔就能明白並且理解，文檔當中可能會存在一部分用戶並不能理解的東西。這時候就需要你使用你所有的超連結以及引用來幫助用戶解決問題。

8.忘記新用戶

當你寫文檔時，你是站在開發者自己的角度上來編寫的，這對於軟件的開發者來說是很容易。然而對於那些新用戶來說，則需要入門文檔。為了使新用戶能夠盡早的了解你的軟件或者熟練掌握使用軟件的方法，我認為應該使用單獨的頁面來為用戶書寫入門文檔。

9.不聽用戶需求

項目的開發者必須聽用戶對整個項目的需求。最有效的方法就是讓更多的人對你的項目進行試用來找出問題。同等重要的是，在聽用戶需求的過程當中，項目開發人員應該考慮到用戶提出這些問題背後的真正原因。

10.不接受用戶輸入

如果你的項目有一個足夠大的用戶群，你可以讓用戶直接將評論添加到文檔當中。我見過的最好的例子是PHP語言，其文檔中的每個頁面允許經過身份驗證的用戶添加評論，或添加的評論不屬於核心文檔。