關於開源文件：程式設計師可能忽略的十件事

　　大多數開源開發人員喜歡思考他們構建軟體的質量，但其文件的質量常常被遺忘。沒有人談論一個專案的文件是多麼出色，但其實文件對一個專案的成功卻有直接的影響。沒有一個良好的文件可能使用者根本不會使用你的專案，亦或者壓根不會喜歡。

　　然而大多數開源專案的文件都是令人極其失望的，主要從以下的幾個方面來體現。

　　1.缺乏一個好的自述或介紹

　　自述是潛在使用者對你專案的第一印象。如果專案在GitHub上，自述自動的顯示在該專案的主頁上。如果你稍微不留神將自述弄錯了，這些潛在的使用者有可能再也不會回來了。所以你的專案必須有一個好的自述來吸引使用者對你的專案產生興趣。

　　自述檔案至少應該包括以下幾點說明：

• 是什麼專案
• 面向何種使用者
• 執行在什麼硬體或者平臺上
• 主要依賴關係
• 如何安裝或者深入的方向指標

　　這些都是寫給那些之前從未聽說過你的專案甚至可能永遠不會考慮你的專案的使用者。當然也不要以為每個閱讀你自述的使用者都知道那是什麼，必要的時候需要做出一些註解以及附上一些有用的連結，方便使用者瞭解你的專案。

　　2.不提供線上文件

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

　　3.只有線上文件

　　這個問題的另一面就是開發人員只提供線上的文件。有些專案不附帶該專案可互動的文件，或者包含的文件是不符合的版本。例如PHP語言不附帶任何文件，如果你想要文件，必須用一個單獨的頁面來開啟他們。然而更糟糕的是，只有核心程式碼可以下載。這樣導致使用者可能不能獲得對自己有用的資訊。

　　開源專案不能想當然的認為使用者訪問網際網路時他們需要線上的文件。當然你也不希望使用者過分的依賴你的專案網站。

　　4.不包含安裝文件

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

　　5.缺乏截圖

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

　　6.缺乏例項

　　對於基於程式碼的專案，模擬的截圖固然是非常不錯的，但是相關的例項也是必不可少的。這些例項不應該是抽象的，而應該是從現實世界當中提取的。花時間建立一些與專案相關的例項，向使用者展示如何解決軟體使用過程中出現的問題。

　　7.不充分的連結和引用

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

　　8.忘記新使用者

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

　　9.不傾聽使用者需求

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

　　10.不接受使用者輸入

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