程式設計師編寫技術文件的新手指南

攝像機從舞臺左邊搖攝。畫面中顯示著一個開啟了空白頁面的編輯器。一個人彎著腰坐在桌子前面，頭朝著桌子。

上面的場景對每個以寫作為生的人來說都很熟悉，空白的頁面混雜著許多情感。它充滿了新開始的興奮和新鮮感。然而也充滿了不知從何起筆的絕望。

讓我來結束這個場景的放映。

這是一篇幫助你給第一個專案寫文件的指南。萬事開頭難，我希望這份指南能把你引導到正確的道路上。最後，你應該有一個可以公開發布的專案。

請輕鬆地閱讀完這篇文章，或者簡單地把它當作參考。

為什麼要寫文件？

你將會在 6 個月後使用你的程式碼

我發現一開始從利己的角度來解釋這個問題會比較有吸引力。寫文件最好的理由就是你將會在 6 個月後使用你的程式碼。你 6 個月前寫的程式碼跟別人寫的程式碼對你來說通常沒有什麼區別。你將會帶著一種熟悉的感覺讀你的程式碼。然後一種不良的預兆悄悄逼近，你發現寫程式碼的人毫無經驗，毫無智慧。

當你讀完幾個月前很簡單易懂或者取巧的程式碼之後，你就會開始同情你的使用者。只要我寫下為什麼我要這麼做，生活就會變得如此簡單。文件能讓你記錄程式碼為什麼這樣寫的原因。同樣地，程式碼註釋解釋了為什麼，而不是怎麼做，文件也是這樣。

你想要別人使用你的程式碼

你已經寫了一段程式碼，並且釋出了它。你這樣做是因為你認為別人可能覺得它有用。但是，人們需要先知道為什麼你的程式碼對他們可能有用，才會決定使用它。文件可以告訴人們這個專案對他們有用。

• 如果人們不知道你專案存在的意義，他們不會使用它。
• 如果人們不知道怎麼安裝你的程式，他們不會使用它。
• 如果人們不知道怎麼使用你的程式碼，他們不會使用它。

只有少數人會深入研究你的程式碼並且使用它。幾乎沒人會使用你的程式碼，除非它有好的文件。如果你真的熱愛你的專案，給它寫文件，讓其他人使用它。

你需要別人的幫助

開源專案是具有魔力的，對嗎？你釋出了程式碼，然後 code gnomes 出現並且讓你的程式碼更好。

當你釋出程式碼的時候會有一種奇妙的感覺產生。它通過各種方式出現，但總是能讓你興奮不已。有人在使用我的程式碼？這是一種混合了恐懼和興奮的感覺。

我創造了價值！

如果它出錯了怎麼辦？！

我是一個開源專案開發者了！

天哪，別人在使用我的程式碼。。。

寫好的文件能夠減輕這種恐懼。很多恐懼來自於給世界創造東西。我最喜歡的關於這個問題的引文如下所示：

恐懼來自於你做著重要的事情。

如果你在做不讓你恐懼的事情，那麼它對你或者世界都沒有益處。

恭喜你感到恐懼！它意味著你在做重要的事情。

實際上，不完全是這樣。

開源專案確實令人感到驚奇，但它同樣必須符合現實世界的規則。你必須有付出，才有收穫。

在你為專案付出大量工作之後，才能獲得貢獻。

在你的專案有使用者之後，才能獲得貢獻。

在你的專案有文件之後，才能獲得貢獻。

文件也為你專案的第一次貢獻提供平臺。很多人從來沒有為開源專案貢獻過，讓他們修改程式碼比修改文件可怕得多。如果你沒有文件，你將失去這類文件貢獻者。

文件讓你的程式碼更好

有一個古老的事實：把東西寫下來幫助你更好地思考。頭腦裡產生一個聽起來不錯的想法很容易，但是把想法寫到紙上就需要思想上的昇華。

寫文件能提升程式碼的設計。在紙上討論你的API和設計決定可以讓你用一種更正式的方式思考它們。它還有一個不錯的副作用：讓別人按照你原來的意圖貢獻程式碼。

你想成為一個更好的寫作者。

寫文件跟大多數人體驗過的寫作方式不同。技術寫作是一種非與生俱來的藝術。寫文件將會是你成為更好的技術寫作者這條路的起點，作為程式設計師，這是一個有用的技能。

寫作會隨著時間的流逝變得更容易。如果你好幾個月沒寫東西，再次動筆就會變得更加困難。邊做專案邊寫文件將會讓你保持一個合理寫作節奏。

用什麼工具寫作

簡單的開始是取得實際成果的最好方式。我將會提供一條平坦的路給你走，在你有了基本的想法之後，你可以擴大範圍。這些工具很強大並且容易使用。這將移除寫作的障礙。

這篇文章中的例子在 Markdown 和 reStructuredText 中都是有效的。reStructuredText 有一點難用，但是更強大。我推薦你兩個都看看，然後決定哪個你想要用。

純文字版本控制

做為程式設計師我們生活中純文字的世界裡。我們的文件工具不應例外。我們想要能把純文字轉化成漂亮的 HTML 的工具。我們還有一些最好的跟蹤檔案變化的工具。為什麼我們寫文件的時候會放棄使用這些工具？這套工作流是強大的，並且對開發者來說很熟悉的。

基本例子

上面的文字將渲染成標題，下面帶著列表。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。

打賞支援我翻譯更多好文章，謝謝！

打賞譯者