大多數(shù)開源項目開發(fā)者只關(guān)注于軟件的質(zhì)量，而常常忘記編寫高品質(zhì)的文檔。但是，文檔的好壞對于一個項目的成功有著至關(guān)重要的作用，它可以幫助用戶快速了解這個項目，或在用戶的使用過程中提供一些幫助。然而，有很多開源項目的文檔令人失望，主要表現(xiàn)在以下幾個方面。
1. 缺乏一個良好的README或介紹
README可以使?jié)撛谟脩魧δ愕捻椖坑幸粋€初步、快速的了解，如果該項目在GitHub上，README文件會自動顯示在該項目的主頁。如果你想一下子吸引住用戶，并讓他們繼續(xù)探索你的項目，那么一個好的介紹必不可少。如果介紹很糟糕，這些用戶可能不會再回來了。
README文件至少應(yīng)該包含：
項目用途
針對人群
運(yùn)行的平臺或硬件
重要依賴
如何安裝，或更深層次的東西
項目README必須要針對那些從來沒聽說過你的項目的人來寫。比如，項目中有一個計算Levenshtein距離的模塊，你不要想當(dāng)然地認(rèn)為每個正在讀README的人都知道Levenshtein是什么東西。你應(yīng)該說明一下，并加上相關(guān)詳細(xì)信息的鏈接，便于人們進(jìn)一步探索。
在介紹一個新東西時，不要再引入其他的新東西，比如“NumberDoodle類似于BongoCalc，但更好”，人們或許壓根不知道BongoCalc。
2. 沒有在線提供文檔
項目的文檔必須能夠在谷歌中查找到，因此，要確保你的文檔在線可用。
我之前發(fā)布了一個開源項目，令我惱火的是，用戶經(jīng)常給我發(fā)郵件問一些我已經(jīng)在FAQ中回答過的問題，后來我才發(fā)現(xiàn)，我沒有將FAQ放在網(wǎng)站上。這是一個比較容易犯的錯誤，因為作者沒有站在用戶的角度考慮問題。
3. 只提供在線文檔
你不能不提供在線文檔，但同時也不能只提供在線文檔。有些項目最終版本中沒有附上文檔，或者包含了項目開發(fā)階段的不完整的文檔，而將最終文檔放在網(wǎng)上，這給無網(wǎng)絡(luò)的用戶，造成了一定的困擾。
比如，Solr項目，有一個非常全面的Wiki(文檔)，但是提供下載的卻是一個2200頁的自動生成的API Javadocs，其中針對最終用戶的唯一的文檔是一個單頁的教程。
PHP語言包也沒有附帶任何文檔，如果你想要文檔，你必須到一個單獨(dú)的頁面。糟糕的是，只提供下載核心文檔，并且還沒有對用戶有幫助的注釋。
開源項目不能想當(dāng)然地認(rèn)為用戶都能上網(wǎng)。你也不能讓用戶過分依賴于項目網(wǎng)站。在過去幾個月中，我已經(jīng)發(fā)現(xiàn)Solr wiki宕機(jī)至少兩次了，而我當(dāng)時正急需解決一個棘手的配置問題。
這一方面做的比較好的是Perl和其CPAN模塊庫。每個模塊文檔都以一種易于閱讀的超鏈接格式提供在search.cpan.org和metacpan.org上。對于離線環(huán)境，每個模塊文檔嵌入在代碼本身上，當(dāng)用戶安裝模塊時，會自動創(chuàng)建本地文檔作為說明手冊。用戶也可以在Shell中使用perldoc Module::Name命令來獲取文檔。無論是在線或是離線，你都可以使用。
4. 文檔沒有自動安裝
這通常是安裝包創(chuàng)建者的錯。比如，在Ubuntu Linux中，Perl語言的文檔時一個獨(dú)立的、可選的包，用戶在安裝時可能會遺漏掉這個選項。盡管節(jié)省了幾MB的磁盤空間，但用戶在需要時無法及時找到。
5. 缺少截圖
有時候，一張圖片勝過千言萬語。
一個屏幕截圖，可以幫助用戶直觀地比較操作結(jié)果，看是否正確地完成了各項任務(wù)，或輕松地找出哪里出現(xiàn)了問題。
現(xiàn)在，使用視頻來介紹項目也變得普遍，視頻可以顯示一個復(fù)雜過程的步驟。比如Plone項目，有一個專門網(wǎng)站來提供視頻教程。但是，視頻還無法取代屏幕截圖，因為用戶無法通過視頻快速找到某些內(nèi)容(需要一點(diǎn)一點(diǎn)看)，且視頻無法被谷歌圖片搜索收錄，屏幕截圖可以。
6. 缺乏現(xiàn)實例子
對于基于代碼的項目，截圖固然不錯，但給出一個實例更實用。這些例子不應(yīng)該是抽象的，而是來自現(xiàn)實世界中的。開發(fā)者應(yīng)該花時間創(chuàng)建一個相關(guān)的例子，來向用戶展示該項目是如何解決問題的。
正如Apache項目的Rich Bowen所說，“一個正確的、功能齊全的、經(jīng)過測試的、有注釋的例子，勝過一頁的乏味介紹。”
7. 缺少鏈接和參考
不要認(rèn)為你要解釋的內(nèi)容是文檔的一部分，或者用戶已經(jīng)在前面讀過，或者知道它們在哪里，就無需再使用超鏈接。比如，你的項目中有一部分代碼作用是操作frobbitz對象，你有必要解釋一下frobbitz對象，或鏈接到相關(guān)頁面。
8. 不考慮新用戶
編寫文檔的時候，不要認(rèn)為一些用戶已經(jīng)知道一些東西而不去詳細(xì)介紹。你應(yīng)該考慮到新用戶，并用一個單獨(dú)的頁面、最好的例子，來讓新用戶快速了解你的項目。
9. 不聽用戶的反饋
你應(yīng)該積極聽取使用你軟件的用戶的建議和需求，比如“如果有一個關(guān)于數(shù)據(jù)庫驅(qū)動程序安裝的介紹或鏈接就好了，這將幫助我安裝這個程序”。
根據(jù)用戶的反饋，創(chuàng)建一個常見問題。并經(jīng)常關(guān)注其他一些網(wǎng)站或論壇，如StackOverflow，并創(chuàng)建一個Google Alert，來了解互聯(lián)網(wǎng)上針對你的項目的討論。
10. 不接受用戶輸入
如果你的項目有足夠大的用戶群，那么你可以考慮讓用戶能夠直接將意見寫到文檔中。我見過最好的例子是PHP，每一頁文檔都允許經(jīng)過身份驗證的用戶在頁面中進(jìn)行注釋，或添加非核心文檔例子。
這些內(nèi)容需要維護(hù)，因為隨著時間的推移，會出現(xiàn)一些過時的注釋，這些需要被淘汰。
11. 必須安裝后才能了解項目的用途
每個軟件項目都需要有一個功能列表和頁面截圖，如果是純粹的代碼項目，比如一個庫，也應(yīng)該有一個示例頁面。
12. 依賴于文檔自動生成
大多時候，軟件開發(fā)者會使用自動化的文檔生成系統(tǒng)，來代替自己的工作。他們忘記了還需要手動寫其他部分。 最壞的情況是，changelog中除了一些提交信息外沒有任何內(nèi)容。changelog應(yīng)該列出新的功能、錯誤修復(fù)以及潛在的兼容性問題，它的目標(biāo)群體是最終用戶。而提交日志是給開發(fā)者看的。
13. 以傲慢的態(tài)度對待小白用戶
不要對用戶的問題都報以“RTFM(Read the Freaking Manual，去讀那些TMD手冊)”的態(tài)度，這可能會嚇走一批潛在的用戶。
如果用戶的問題可以在文檔中找到，但他們沒有這樣做，不要認(rèn)為這是愚蠢的。有可能是因為你的文檔寫得糟糕，難以閱讀，或者不完整。你需要耐心地改善“入門”章節(jié)，說明軟件的目的是什么，或者給用戶指明在哪里可以找到相關(guān)的信息。
