開源專案文件應規避的13處“硬傷”

　　大多數開源專案開發者只關注於軟體的質量，而常常忘記編寫高品質的文件。但是，文件的好壞對於一個專案的成功有著至關重要的作用，它可以幫助使用者快速瞭解這個專案，或在使用者的使用過程中提供一些幫助。

　　然而，有很多開源專案的文件令人失望，主要表現在以下幾個方面。

　　1.  缺乏一個良好的README或介紹

　　README可以使潛在使用者對你的專案有一個初步、快速的瞭解，如果該專案在GitHub上，README檔案會自動顯示在該專案的主頁。如果你想一下子吸引住使用者，並讓他們繼續探索你的專案，那麼一個好的介紹必不可少。如果介紹很糟糕，這些使用者可能不會再回來了。

　　README檔案至少應該包含：

• 專案用途
• 針對人群
• 執行的平臺或硬體
• 重要依賴
• 如何安裝，或更深層次的東西

　　專案README必須要針對那些從來沒聽說過你的專案的人來寫。比如，專案中有一個計算Levenshtein距離的模組，你不要想當然地認為每個正在讀README的人都知道Levenshtein是什麼東西。你應該說明一下，並加上相關詳細資訊的連結，便於人們進一步探索。

　　在介紹一個新東西時，不要再引入其他的新東西，比如“NumberDoodle類似於BongoCalc，但更好”，人們或許壓根不知道BongoCalc。

　　2.  沒有線上提供文件

　　專案的文件必須能夠在谷歌中查詢到，因此，要確保你的文件線上可用。

　　我之前釋出了一個開源專案，令我惱火的是，使用者經常給我發郵件問一些我已經在FAQ中回答過的問題，後來我才發現，我沒有將FAQ放在網站上。這是一個比較容易犯的錯誤，因為作者沒有站在使用者的角度考慮問題。

　　3.  只提供線上文件

　　你不能不提供線上文件，但同時也不能只提供線上文件。有些專案最終版本中沒有附上文件，或者包含了專案開發階段的不完整的文件，而將最終文件放在網上，這給無網路的使用者，造成了一定的困擾。

　　比如，Solr專案，有一個非常全面的Wiki（文件），但是提供下載的卻是一個2200頁的自動生成的API Javadocs，其中針對終端使用者的唯一的文件是一個單頁的教程。

　　PHP語言包也沒有附帶任何文件，如果你想要文件，你必須到一個單獨的頁面。糟糕的是，只提供下載核心文件，並且還沒有對使用者有幫助的註釋。

　　開源專案不能想當然地認為使用者都能上網。你也不能讓使用者過分依賴於專案網站。在過去幾個月中，我已經發現Solr wiki當機至少兩次了，而我當時正急需解決一個棘手的配置問題。

　　這一方面做的比較好的是Perl和其CPAN模組庫。每個模組文件都以一種易於閱讀的超連結格式提供在search.cpan.org和metacpan.org上。對於離線環境，每個模組文件嵌入在程式碼本身上，當使用者安裝模組時，會自動建立本地文件作為說明手冊。使用者也可以在Shell中使用perldoc Module::Name命令來獲取文件。無論是線上或是離線，你都可以使用。

　　4.  文件沒有自動安裝

　　這通常是安裝包建立者的錯。比如，在Ubuntu Linux中，Perl語言的文件時一個獨立的、可選的包，使用者在安裝時可能會遺漏掉這個選項。儘管節省了幾MB的磁碟空間，但使用者在需要時無法及時找到。

　　5.  缺少截圖

　　有時候，一張圖片勝過千言萬語。

　　一個螢幕截圖，可以幫助使用者直觀地比較操作結果，看是否正確地完成了各項任務，或輕鬆地找出哪裡出現了問題。

　　現在，使用視訊來介紹專案也變得普遍，視訊可以顯示一個複雜過程的步驟。比如Plone專案，有一個專門網站來提供視訊教程。但是，視訊還無法取代螢幕截圖，因為使用者無法通過視訊快速找到某些內容（需要一點一點看），且視訊無法被谷歌圖片搜尋收錄，螢幕截圖可以。

　　6.  缺乏現例項子

　　對於基於程式碼的專案，截圖固然不錯，但給出一個例項更實用。這些例子不應該是抽象的，而是來自現實世界中的。開發者應該花時間建立一個相關的例子，來向使用者展示該專案是如何解決問題的。

　　正如Apache專案的Rich Bowen所說，“一個正確的、功能齊全的、經過測試的、有註釋的例子，勝過一頁的乏味介紹。”

　　7.  缺少連結和參考

　　不要認為你要解釋的內容是文件的一部分，或者使用者已經在前面讀過，或者知道它們在哪裡，就無需再使用超連結。比如，你的專案中有一部分程式碼作用是操作frobbitz物件，你有必要解釋一下frobbitz物件，或連結到相關頁面。

　　8.  不考慮新使用者

　　編寫文件的時候，不要認為一些使用者已經知道一些東西而不去詳細介紹。你應該考慮到新使用者，並用一個單獨的頁面、最好的例子，來讓新使用者快速瞭解你的專案。

　　9.  不聽使用者的反饋

　　你應該積極聽取使用你軟體的使用者的建議和需求，比如“如果有一個關於資料庫驅動程式安裝的介紹或連結就好了，這將幫助我安裝這個程式”。

　　根據使用者的反饋，建立一個常見問題。並經常關注其他一些網站或論壇，如StackOverflow，並建立一個Google Alert，來了解網際網路上針對你的專案的討論。

　　10.  不接受使用者輸入

　　如果你的專案有足夠大的使用者群，那麼你可以考慮讓使用者能夠直接將意見寫到文件中。我見過最好的例子是PHP，每一頁文件都允許經過身份驗證的使用者在頁面中進行註釋，或新增非核心文件例子。

　　這些內容需要維護，因為隨著時間的推移，會出現一些過時的註釋，這些需要被淘汰。

　　11.  必須安裝後才能瞭解專案的用途

　　每個軟體專案都需要有一個功能列表和頁面截圖，如果是純粹的程式碼專案，比如一個庫，也應該有一個示例頁面。

　　12.  依賴於文件自動生成

　　大多時候，軟體開發者會使用自動化的文件生成系統，來代替自己的工作。他們忘記了還需要手動寫其他部分。

　　最壞的情況是，changelog中除了一些提交資訊外沒有任何內容。changelog應該列出新的功能、錯誤修復以及潛在的相容性問題，它的目標群體是終端使用者。而提交日誌是給開發者看的。

　　13.  以傲慢的態度對待小白使用者

　　不要對使用者的問題都報以“RTFM（Read the Freaking Manual，去讀那些TMD手冊）”的態度，這可能會嚇走一批潛在的使用者。

　　如果使用者的問題可以在文件中找到，但他們沒有這樣做，不要認為這是愚蠢的。有可能是因為你的文件寫得糟糕，難以閱讀，或者不完整。你需要耐心地改善“入門”章節，說明軟體的目的是什麼，或者給使用者指明在哪裡可以找到相關的資訊。

　　英文原文：13 Things People Hate about Your Open Source Docs