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

　　1. 缺乏一個(gè)良好的README或介紹

　　README可以使?jié)撛谟脩魧?duì)你的項(xiàng)目有一個(gè)初步、快速的了解，如果該項(xiàng)目在GitHub上，README文件會(huì)自動(dòng)顯示在該項(xiàng)目的主頁(yè)。如果你想一下子吸引住用戶，并讓他們繼續(xù)探索你的項(xiàng)目，那么一個(gè)好的介紹必不可少。如果介紹很糟糕，這些用戶可能不會(huì)再回來(lái)了。

　　README文件至少應(yīng)該包含：

　　項(xiàng)目用途

　　針對(duì)人群

　　運(yùn)行的平臺(tái)或硬件

　　重要依賴

　　如何安裝，或更深層次的東西

　　項(xiàng)目README必須要針對(duì)那些從來(lái)沒(méi)聽(tīng)說(shuō)過(guò)你的項(xiàng)目的人來(lái)寫。比如，項(xiàng)目中有一個(gè)計(jì)算Levenshtein距離的模塊，你不要想當(dāng)然地認(rèn)為每個(gè)正在讀README的人都知道Levenshtein是什么東西。你應(yīng)該說(shuō)明一下，并加上相關(guān)詳細(xì)信息的鏈接，便于人們進(jìn)一步探索。

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

　　2. 沒(méi)有在線提供文檔

　　項(xiàng)目的文檔必須能夠在谷歌中查找到，因此，要確保你的文檔在線可用。

　　我之前發(fā)布了一個(gè)開(kāi)源項(xiàng)目，令我惱火的是，用戶經(jīng)常給我發(fā)郵件問(wèn)一些我已經(jīng)在FAQ中回答過(guò)的問(wèn)題，后來(lái)我才發(fā)現(xiàn)，我沒(méi)有將FAQ放在網(wǎng)站上。這是一個(gè)比較容易犯的錯(cuò)誤，因?yàn)樽髡邲](méi)有站在用戶的角度考慮問(wèn)題。

　　3. 只提供在線文檔

　　你不能不提供在線文檔，但同時(shí)也不能只提供在線文檔。有些項(xiàng)目最終版本中沒(méi)有附上文檔，或者包含了項(xiàng)目開(kāi)發(fā)階段的不完整的文檔，而將最終文檔放在網(wǎng)上，這給無(wú)網(wǎng)絡(luò)的用戶，造成了一定的困擾。

　　比如，Solr項(xiàng)目，有一個(gè)非常全面的Wiki(文檔)，但是提供下載的卻是一個(gè)2200頁(yè)的自動(dòng)生成的API Javadocs，其中針對(duì)最終用戶的唯一的文檔是一個(gè)單頁(yè)的教程。

　　PHP語(yǔ)言包也沒(méi)有附帶任何文檔，如果你想要文檔，你必須到一個(gè)單獨(dú)的頁(yè)面。糟糕的是，只提供下載核心文檔，并且還沒(méi)有對(duì)用戶有幫助的注釋。

　　開(kāi)源項(xiàng)目不能想當(dāng)然地認(rèn)為用戶都能上網(wǎng)。你也不能讓用戶過(guò)分依賴于項(xiàng)目網(wǎng)站。在過(guò)去幾個(gè)月中，我已經(jīng)發(fā)現(xiàn)Solr wiki宕機(jī)至少兩次了，而我當(dāng)時(shí)正急需解決一個(gè)棘手的配置問(wèn)題。

　　這一方面做的比較好的是Perl和其CPAN模塊庫(kù)。每個(gè)模塊文檔都以一種易于閱讀的超鏈接格式提供在search.cpan.org和metacpan.org上。對(duì)于離線環(huán)境，每個(gè)模塊文檔嵌入在代碼本身上，當(dāng)用戶安裝模塊時(shí)，會(huì)自動(dòng)創(chuàng)建本地文檔作為說(shuō)明手冊(cè)。用戶也可以在Shell中使用perldoc Module::Name命令來(lái)獲取文檔。無(wú)論是在線或是離線，你都可以使用。

　　4. 文檔沒(méi)有自動(dòng)安裝

　　這通常是安裝包創(chuàng)建者的錯(cuò)。比如，在Ubuntu Linux中，Perl語(yǔ)言的文檔時(shí)一個(gè)獨(dú)立的、可選的包，用戶在安裝時(shí)可能會(huì)遺漏掉這個(gè)選項(xiàng)。盡管節(jié)省了幾MB的磁盤空間，但用戶在需要時(shí)無(wú)法及時(shí)找到。

　　5. 缺少截圖

　　有時(shí)候，一張圖片勝過(guò)千言萬(wàn)語(yǔ)。

　　一個(gè)屏幕截圖，可以幫助用戶直觀地比較操作結(jié)果，看是否正確地完成了各項(xiàng)任務(wù)，或輕松地找出哪里出現(xiàn)了問(wèn)題。

　　現(xiàn)在，使用視頻來(lái)介紹項(xiàng)目也變得普遍，視頻可以顯示一個(gè)復(fù)雜過(guò)程的步驟。比如Plone項(xiàng)目，有一個(gè)專門網(wǎng)站來(lái)提供視頻教程。但是，視頻還無(wú)法取代屏幕截圖，因?yàn)橛脩魺o(wú)法通過(guò)視頻快速找到某些內(nèi)容(需要一點(diǎn)一點(diǎn)看)，且視頻無(wú)法被谷歌圖片搜索收錄，屏幕截圖可以。

　　6. 缺乏現(xiàn)實(shí)例子

　　對(duì)于基于代碼的項(xiàng)目，截圖固然不錯(cuò)，但給出一個(gè)實(shí)例更實(shí)用。這些例子不應(yīng)該是抽象的，而是來(lái)自現(xiàn)實(shí)世界中的。開(kāi)發(fā)者應(yīng)該花時(shí)間創(chuàng)建一個(gè)相關(guān)的例子，來(lái)向用戶展示該項(xiàng)目是如何解決問(wèn)題的。

　　正如Apache項(xiàng)目的Rich Bowen所說(shuō)，“一個(gè)正確的、功能齊全的、經(jīng)過(guò)測(cè)試的、有注釋的例子，勝過(guò)一頁(yè)的乏味介紹。”

　　7. 缺少鏈接和參考

　　不要認(rèn)為你要解釋的內(nèi)容是文檔的一部分，或者用戶已經(jīng)在前面讀過(guò)，或者知道它們?cè)谀睦铮蜔o(wú)需再使用超鏈接。比如，你的項(xiàng)目中有一部分代碼作用是操作frobbitz對(duì)象，你有必要解釋一下frobbitz對(duì)象，或鏈接到相關(guān)頁(yè)面。

　　8. 不考慮新用戶

　　編寫文檔的時(shí)候，不要認(rèn)為一些用戶已經(jīng)知道一些東西而不去詳細(xì)介紹。你應(yīng)該考慮到新用戶，并用一個(gè)單獨(dú)的頁(yè)面、最好的例子，來(lái)讓新用戶快速了解你的項(xiàng)目。

　　9. 不聽(tīng)用戶的反饋

　　你應(yīng)該積極聽(tīng)取使用你軟件的用戶的建議和需求，比如“如果有一個(gè)關(guān)于數(shù)據(jù)庫(kù)驅(qū)動(dòng)程序安裝的介紹或鏈接就好了，這將幫助我安裝這個(gè)程序”。

　　根據(jù)用戶的反饋，創(chuàng)建一個(gè)常見(jiàn)問(wèn)題。并經(jīng)常關(guān)注其他一些網(wǎng)站或論壇，如StackOverflow，并創(chuàng)建一個(gè)Google Alert，來(lái)了解互聯(lián)網(wǎng)上針對(duì)你的項(xiàng)目的討論。

　　10. 不接受用戶輸入

　　如果你的項(xiàng)目有足夠大的用戶群，那么你可以考慮讓用戶能夠直接將意見(jiàn)寫到文檔中。我見(jiàn)過(guò)最好的例子是PHP，每一頁(yè)文檔都允許經(jīng)過(guò)身份驗(yàn)證的用戶在頁(yè)面中進(jìn)行注釋，或添加非核心文檔例子。

　　這些內(nèi)容需要維護(hù)，因?yàn)殡S著時(shí)間的推移，會(huì)出現(xiàn)一些過(guò)時(shí)的注釋，這些需要被淘汰。

　　11. 必須安裝后才能了解項(xiàng)目的用途

　　每個(gè)軟件項(xiàng)目都需要有一個(gè)功能列表和頁(yè)面截圖，如果是純粹的代碼項(xiàng)目，比如一個(gè)庫(kù)，也應(yīng)該有一個(gè)示例頁(yè)面。

　　12. 依賴于文檔自動(dòng)生成

　　大多時(shí)候，軟件開(kāi)發(fā)者會(huì)使用自動(dòng)化的文檔生成系統(tǒng)，來(lái)代替自己的工作。他們忘記了還需要手動(dòng)寫其他部分。 最壞的情況是，changelog中除了一些提交信息外沒(méi)有任何內(nèi)容。changelog應(yīng)該列出新的功能、錯(cuò)誤修復(fù)以及潛在的兼容性問(wèn)題，它的目標(biāo)群體是最終用戶。而提交日志是給開(kāi)發(fā)者看的。

　　13. 以傲慢的態(tài)度對(duì)待小白用戶

　　不要對(duì)用戶的問(wèn)題都報(bào)以“RTFM(Read the Freaking Manual，去讀那些TMD手冊(cè))”的態(tài)度，這可能會(huì)嚇走一批潛在的用戶。

　　如果用戶的問(wèn)題可以在文檔中找到，但他們沒(méi)有這樣做，不要認(rèn)為這是愚蠢的。有可能是因?yàn)槟愕奈臋n寫得糟糕，難以閱讀，或者不完整。你需要耐心地改善“入門”章節(jié)，說(shuō)明軟件的目的是什么，或者給用戶指明在哪里可以找到相關(guān)的信息。