為什麼要寫文檔?
你將會在 6 個月後使用你的代碼
我發現一開始從利己的角度來解釋這個問題會比較有吸引力。寫文檔最好的理由就是你將會在 6 個月後使用你的代碼。你 6 個月前寫的代碼跟別人寫的代碼對你來說通常沒有什麼區別。你將會帶著一種熟悉的感覺讀你的代碼。然後一種不良的預兆悄悄逼近,你發現寫代碼的人毫無經驗,毫無智慧。
當你讀完幾個月前很簡單易懂或者取巧的代碼之後,你就會開始同情你的用戶。只要我寫下為什麼我要這麼做,生活就會變得如此簡單。文檔能讓你記錄代碼為什麼這樣寫的原因。同樣地,代碼注釋解釋了為什麼,而不是怎麼做,文檔也是這樣。
你想要別人使用你的代碼
你已經寫了一段代碼,並且發布了它。你這樣做是因為你認為別人可能覺得它有用。但是,人們需要先知道為什麼你的代碼對他們可能有用,才會決定使用它。文檔可以告訴人們這個項目對他們有用。
如果人們不知道你項目存在的意義,他們不會使用它。
如果人們不知道怎麼安裝你的程序,他們不會使用它。
如果人們不知道怎麼使用你的代碼,他們不會使用它。
只有少數人會深入研究你的代碼並且使用它。幾乎沒人會使用你的代碼,除非它有好的文檔。如果你真的熱愛你的項目,給它寫文檔,讓其他人使用它。
你需要別人的幫助
開源項目是具有魔力的,對嗎?你發布了代碼,然後 code gnomes 出現並且讓你的代碼更好。
當你發布代碼的時候會有一種奇妙的感覺產生。它通過各種方式出現,但總是能讓你興奮不已。有人在使用我的代碼?這是一種混合了恐懼和興奮的感覺。
我創造了價值!
如果它出錯了怎麼辦?!
我是一個開源項目開發者了!
天哪,別人在使用我的代碼。。。
寫好的文檔能夠減輕這種恐懼。很多恐懼來自於給世界創造東西。我最喜歡的關於這個問題的引文如下所示:
恐懼來自於你做著重要的事情。
如果你在做不讓你恐懼的事情,那麼它對你或者世界都沒有益處。
恭喜你感到恐懼!它意味著你在做重要的事情。
實際上,不完全是這樣。
開源項目確實令人感到驚奇,但它同樣必須符合現實世界的規則。你必須有付出,才有收獲。
在你為項目付出大量工作之後,才能獲得貢獻。
在你的項目有用戶之後,才能獲得貢獻。
在你的項目有文檔之後,才能獲得貢獻。
文檔也為你項目的第一次貢獻提供平台。很多人從來沒有為開源項目貢獻過,讓他們修改代碼比修改文檔可怕得多。如果你沒有文檔,你將失去這類文檔貢獻者。
文檔讓你的代碼更好
有一個古老的事實:把東西寫下來幫助你更好地思考。頭腦裡產生一個聽起來不錯的想法很容易,但是把想法寫到紙上就需要思想上的升華。
寫文檔能提升代碼的設計。在紙上討論你的API和設計決定可以讓你用一種更正式的方式思考它們。它還有一個不錯的副作用:讓別人按照你原來的意圖貢獻代碼。
你想成為一個更好的寫作者。
寫文檔跟大多數人體驗過的寫作方式不同。技術寫作是一種非與生俱來的藝術。寫文檔將會是你成為更好的技術寫作者這條路的起點,作為程序員,這是一個有用的技能。
寫作會隨著時間的流逝變得更容易。如果你好幾個月沒寫東西,再次動筆就會變得更加困難。邊做項目邊寫文檔將會讓你保持一個合理寫作節奏。
用什麼工具寫作
簡單的開始是取得實際成果的最好方式。我將會提供一條平坦的路給你走,在你有了基本的想法之後,你可以擴大范圍。這些工具很強大並且容易使用。這將移除寫作的障礙。
這篇文章中的例子在 Markdown 和 reStructuredText 中都是有效的。reStructuredText 有一點難用,但是更強大。我推薦你兩個都看看,然後決定哪個你想要用。
純文本版本控制
做為程序員我們生活中純文本的世界裡。我們的文檔工具不應例外。我們想要能把純文本轉化成漂亮的 HTML 的工具。我們還有一些最好的跟蹤文件變化的工具。為什麼我們寫文檔的時候會放棄使用這些工具?這套工作流是強大的,並且對開發者來說很熟悉的。
基本例子
Resources
---------
* Online documentation: http://docs.writethedocs.org/
* Conference: http://conf.writethedocs.org/
上面的文字將渲染成標題,下面帶著列表。URLs 將會被自動超鏈接。這寫起來很容易,不但作為純文本有意義,而且還能很好的渲染成 HTML。
README
你第一個應該寫的文檔是 README。如果你提供了合適的擴展名,代碼托管服務會自動把你的 README 渲染成 HTML。它也是大多數用戶跟你的項目的第一次互動。所以,一個可靠的 README 對你的項目十分有用。
有些人甚至 從 README 開始做項目。
文檔寫什麼
現在我們來討論重要的事情。確保你的用戶能得到他們需要的所有信息,但不要太多。
首先,你需要問自己:文檔是為誰而寫。一開始,你只需要吸引兩類的讀者:
用戶
開發者
用戶是指那些只是想使用你的代碼,而不管關心它怎麼工作的人。開發者是指那些想要給你的代碼做貢獻的人。
你的項目解決了哪些問題
很多人會通過你的文檔搞清楚你的項目是什麼。有人會提到它,有人會隨機地用 Google 搜索一個短語。你應該解釋你的項目做了什麼和它存在的意義。Fabric 這方面做的很好。
一個代碼的小例子
提供一個生動的例子來告知用戶你的項目通常會被用來做什麼。 Requests 是一個很好的例子。
一個代碼和問題追蹤的鏈接
人們有時候喜歡浏覽源代碼。他們可能對歸檔他們發現的代碼 BUG 感興趣。盡可能地讓那些想要為項目做貢獻的人做這件事很容易。我認為 Python Guide 做得很好,因為它有指向代碼部分的鏈接。
常見問題(FAQ)
很多人會有相同的問題。如果問題一直發生,你應該適當地修改你的文檔或者代碼來解決問題。但是總是有一些經常被問的關於項目的問題,不能改變的的事情等。把這些記錄在文檔中,並且使其保持最新。FAQs 通常會過時,但當它們被很好的維護時,它們就是黃金資源。 Tastypie 做得很好,它把 FAQs 整理成“Cookbook”。
如何獲取支持
郵件列表?IRC 頻道?文檔要記錄如何獲取幫助和跟項目社區交流。 Django 這方面做得很好。
給貢獻者的信息
在項目中,人們通常有怎麼做事情的標准。你應該記錄在文檔上,以便於別人寫代碼時能符合項目的標准。Open Comparison 這方面做的很好。
安裝說明
一旦人們決定使用你的代碼,他們需要知道如何獲取它和運行它。但願你的安裝指令只有幾行用於基本使用。如果有必要,給出提供更多信息和說明的頁面鏈接。我認為 Read the Docs 中我們做得很好。
你的項目許可證
BSD?MIT? GPL? 這些證書可能對你來說沒什麼,但是使用你代碼的人會很關心這個。考慮一下你想要用什麼證書發布你的項目,務必選擇一個互聯網上的標准許可證。
下一步做什麼
在你遵循上面的指南之後,我們相信你的項目將會成功。進一步的參考資料,查看這篇文章 如何維護一個開源項目。
模板
給你一個 README 的模板。如果你使用 markdown 的語法,把它命名為 README.md。如果你使用 reStructuredText 的語法,把它命名為 README.rst。
$project
========
$project will solve your problem of where to start with documentation,
by providing a basic explanation of how to do it easily.
Look how easy it is to use:
import project
# Get your stuff done
project.do_stuff()
Features
--------
- Be awesome
- Make things faster
Installation
------------
Install $project by running:
install project
Contribute
----------
- Issue Tracker: github.com/$project/$project/issues
- Source Code: github.com/$project/$project
Support
-------
If you are having issues, please let us know.
We have a mailing list located at: [email protected]
License
-------
The project is licensed under the BSD license.
