關于開源文檔：程序員可能忽略的十件事

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

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

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

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

        自述文件至少應該包括以下幾點說明：

• 是什么項目
• 面向何種用戶
• 運行在什么硬件或者平臺上
• 主要依賴關系
• 如何安裝或者深入的方向指針

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

        2. 不提供在線文檔

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

        3. 只有在線文檔

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

        開源項目不能想當然的認為用戶訪問互聯網時他們需要在線的文檔。當然你也不希望用戶過分的依賴你的項目網站。

        4. 不包含安裝文檔

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

        5. 缺乏截圖

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

        6. 缺乏實例

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

        7. 不充分的鏈接和引用

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

        8. 忘記新用戶

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

        9. 不傾聽用戶需求

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

        10. 不接受用戶輸入

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