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

via:

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

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

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

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

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

是什麼專案

面向何種使用者

執行在什麼硬體或者平台上

主要依賴關係

如何安裝或者深入的方向指標

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

4. 不包含安裝文件

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

5. 缺乏截圖

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

6. 缺乏例項

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

7. 不充分的鏈結和引用

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

8. 忘記新使用者

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

9. 不傾聽使用者需求

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

10. 不接受使用者輸入

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