[[61098]]

大多數開源項目開發者只關注于軟件的質量，而常常忘記編寫高品質的文檔。但是，文檔的好壞對于一個項目的成功有著至關重要的作用，它可以幫助用戶快速了解這個項目，或在用戶的使用過程中提供一些幫助。然而，有很多開源項目的文檔令人失望，主要表現在以下幾個方面。

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