開源項目文檔13處應規避

來源:互聯網
上載者:User

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

然而,有很多開源項目的文檔令人失望,主要表現在以下幾個方面。 

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

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

README檔案至少應該包含: 



  • 項目用途
  • 針對人群
  • 啟動並執行平台或硬體
  • 重要依賴
  • 如何安裝,或更深層次的東西


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

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

2.  沒有線上提供文檔 

項目的文檔必須能夠在Google中尋找到,因此,要確保你的文檔線上可用。 

我之前發布了一個開源項目,令我惱火的是,使用者經常給我發郵件問一些我已經在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項目,有一個專門網站來提供視頻教程。但是,視頻還無法取代螢幕截圖,因為使用者無法通過視頻快速找到某些內容(需要一點一點看),且視頻無法被Google圖片搜尋收錄,螢幕截圖可以。 

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



相關文章

Beyond APAC's No.1 Cloud

19.6% IaaS Market Share in Asia Pacific - Gartner IT Service report, 2018

Learn more >

Apsara Conference 2019

The Rise of Data Intelligence, September 25th - 27th, Hangzhou, China

Learn more >

Alibaba Cloud Free Trial

Learn and experience the power of Alibaba Cloud with a free trial worth $300-1200 USD

Learn more >

聯繫我們

該頁面正文內容均來源於網絡整理,並不代表阿里雲官方的觀點,該頁面所提到的產品和服務也與阿里云無關,如果該頁面內容對您造成了困擾,歡迎寫郵件給我們,收到郵件我們將在5個工作日內處理。

如果您發現本社區中有涉嫌抄襲的內容,歡迎發送郵件至: info-contact@alibabacloud.com 進行舉報並提供相關證據,工作人員會在 5 個工作天內聯絡您,一經查實,本站將立刻刪除涉嫌侵權內容。