[[61098]]

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

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

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

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

• 項(xiàng)目用途
• 針對(duì)人群
• 運(yùn)行的平臺(tái)或硬件
• 重要依賴
• 如何安裝，或更深層次的東西

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

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

2. 沒有在線提供文檔

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

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

3. 只提供在線文檔

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

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

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

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

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

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

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

5. 缺少截圖

有時(shí)候，一張圖片勝過千言萬語。

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

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

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

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

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

7. 缺少鏈接和參考

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

8. 不考慮新用戶

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

9. 不聽用戶的反饋

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

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

10. 不接受用戶輸入

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

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

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

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

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

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

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

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

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

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