程序員編寫技術(shù)文檔的新手指南

程序員編寫技術(shù)文檔的新手指南攝像機從舞臺左邊搖攝。畫面中顯示著一個打開了空白頁面的編輯器。一個人彎著腰坐在桌子前面，頭朝著桌子。上面的場景對每個以寫作為生的人來說都很熟悉，空白的頁面混雜著許多情感。它充滿了新開始的興奮和新鮮感。然而也充滿了不知從何起筆的絕望。讓我來結(jié)束這個場景的放映。這是一篇幫助你給第一個項目寫文檔的指南。萬事開頭難，我希望這份指南能把你引導到正確的道路上。最后，你應該有一個可以公開發(fā)布的項目。請輕松地閱讀完這篇文章，或者簡單地把它當作參考。為什么要寫文檔？你將會在6個月后使用你的代碼我發(fā)現(xiàn)一開始從利己的角度來解釋這個問題會比較有吸引力。寫文檔最好的理由就是你將會在6個月后使用你的代碼。你6個月前寫的代碼跟別人寫的代碼對你來說通常沒有什么區(qū)別。你將會帶著一種熟悉的感覺讀你的代碼。然后一種不良的預兆悄悄逼近，你發(fā)現(xiàn)寫代碼的人毫無經(jīng)驗，毫無智慧。當你讀完幾個月前很簡單易懂或者取巧的代碼之后，你就會開始同情你的用戶。只要我寫下為什么我要這么做，生活就會變得如此簡單。文檔能讓你記錄代碼為什么這樣寫的原因。同樣地，代碼注釋解釋了為什么，而不是怎么做，文檔也是這樣。你想要別人使用你的代碼你已經(jīng)寫了一段代碼，并且發(fā)布了它。你這樣做是因為你認為別人可能覺得它有用。但是，人們需要先知道為什么你的代碼對他們可能有用，才會決定使用它。文檔可以告訴人們這個項目對他們有用。如果人們不知道你項目存在的意義，他們不會使用它。如果人們不知道怎么安裝你的程序，他們不會使用它。如果人們不知道怎么使用你的代碼，他們不會使用它。只有少數(shù)人會深入研究你的代碼并且使用它。幾乎沒人會使用你的代碼，除非它有好的文檔。如果你真的熱愛你的項目，給它寫文檔，讓其他人使用它。你需要別人的幫助開源項目是具有魔力的，對嗎？你發(fā)布了代碼，然后codegnomes出現(xiàn)并且讓你的代碼更好。當你發(fā)布代碼的時候會有一種奇妙的感覺產(chǎn)生。它通過各種方式出現(xiàn)，但總是能讓你興奮不已。有人在使用我的代碼？這是一種混合了恐懼和興奮的感覺。我創(chuàng)造了價值！如果它出錯了怎么辦？！我是一個開源項目開發(fā)者了！天哪，別人在使用我的代碼。。。寫好的文檔能夠減輕這種恐懼。很多恐懼來自于給世界創(chuàng)造東西。我最喜歡的關(guān)于這個問題的引文如下所示：恐懼來自于你做著重要的事情。如果你在做不讓你恐懼的事情，那么它對你或者世界都沒有益處。恭喜你感到恐懼！它意味著你在做重要的事情。實際上，不完全是這樣。開源項目確實令人感到驚奇，但它同樣必須符合現(xiàn)實世界的規(guī)則。你必須有付出，才有收獲。在你為項目付出大量工作之后，才能獲得貢獻。在你的項目有用戶之后，才能獲得貢獻。在你的項目有文檔之后，才能獲得貢獻。文檔也為你項目的第一次貢獻提供平臺。很多人從來沒有為開源項目貢獻過，讓他們修改代碼比修改文檔可怕得多。如果你沒有文檔，你將失去這類文檔貢獻者。文檔讓你的代碼更好有一個古老的事實：把東西寫下來幫助你更好地思考。頭腦里產(chǎn)生一個聽起來不錯的想法很容易，但是把想法寫到紙上就需要思想上的升華。寫文檔能提升代碼的設計。在紙上討論你的API和設計決定可以讓你用一種更正式的方式思考它們。它還有一個不錯的副作用：讓別人按照你原來的意圖貢獻代碼。你想成為一個更好的寫。寫文檔跟大多數(shù)人體驗過的寫作方式不同。技術(shù)寫作是一種非與生俱來的藝術(shù)。寫文檔將會是你成為更好的技術(shù)寫這條路的起點，作為程序員，這是一個有用的技能。寫作會隨著時間的流逝變得更容易。如果你好幾個月沒寫東西，再次動筆就會變得更加困難。邊做項目邊寫文檔將會讓你保持一個合理寫作節(jié)奏。用什么工具寫作簡單的開始是取得實際成果的最好方式。我將會提供一條平坦的路給你走，在你有了基本的想法之后，你可以擴大范圍。這些工具很強大并且容易使用。這將移除寫作的障礙。這篇文章中的例子在Markdown和reStructuredText中都是有效的。reStructuredText有一點難用，但是更強大。我推薦你兩個都看看，然后決定哪個你想要用。純文本版本控制做為程序員我們生活中純文本的世界里。我們的文檔工具不應例外。我們想要能把純文本轉(zhuǎn)化成漂亮的HTML的工具。我們還有一些最好的跟蹤文件變化的工具。為什么我們寫文檔的時候會放棄使用這些工具？這套工作流是強大的，并且對開發(fā)者來說很熟悉的?；纠覴esources---------

*

Online

documentation:

/*

Conference:

/上面的文字將渲染成標題，下面帶著列表。URLs將會被自動超鏈接。這寫起來很容易，不但作為純文本有意義，而且還能很好的渲染成HTML。README你第一個應該寫的文檔是README。如果你提供了合適的擴展名，代碼托管服務會自動把你的README渲染成HTML。它也是大多數(shù)用戶跟你的項目的第一次互動。所以，一個可靠的README對你的項目十分有用。有些人甚至從README開始做項目。文檔寫什么現(xiàn)在我們來討論重要的事情。確保你的用戶能得到他們需要的所有信息，但不要太多。首先，你需要問自己：文檔是為誰而寫。一開始，你只需要吸引兩類的讀者：用戶開發(fā)者用戶是指那些只是想使用你的代碼，而不管關(guān)心它怎么工作的人。開發(fā)者是指那些想要給你的代碼做貢獻的人。你的項目解決了哪些問題很多人會通過你的文檔搞清楚你的項目是什么。有人會提到它，有人會隨機地用Google搜索一個短語。你應該解釋你的項目做了什么和它存在的意義。Fabric這方面做的很好。一個代碼的小例子提供一個生動的例子來告知用戶你的項目通常會被用來做什么。Requests是一個很好的例子。一個代碼和問題追蹤的鏈接人們有時候喜歡瀏覽源代碼。他們可能對歸檔他們發(fā)現(xiàn)的代碼BUG感興趣。盡可能地讓那些想要為項目做貢獻的人做這件事很容易。我認為PythonGuide做得很好，因為它有指向代碼部分的鏈接。常見問題（FAQ）很多人會有相同的問題。如果問題一直發(fā)生，你應該適當?shù)匦薷哪愕奈臋n或者代碼來解決問題。但是總是有一些經(jīng)常被問的關(guān)于項目的問題，不能改變的的事情等。把這些記錄在文檔中，并且使其保持最新。FAQs通常會過時，但當它們被很好的維護時，它們就是黃金資源。Tastypie做得很好，它把FAQs整理成“Cookbook”。如何獲取支持郵件列表？IRC頻道？文檔要記錄如何獲取幫助和跟項目社區(qū)交流。Django這方面做得很好。給貢獻者的信息在項目中，人們通常有怎么做事情的標準。你應該記錄在文檔上，以便于別人寫代碼時能符合項目的標準。OpenComparison這方面做的很好。安裝說明一旦人們決定使用你的代碼，他們需要知道如何獲取它和運行它。但愿你的安裝指令只有幾行用于基本使用。如果有必要，給出提供更多信息和說明的頁面鏈接。我認為ReadtheDocs中我們做得很好。你的項目許可證BSD?MIT?GPL?這些證書可能對你來說沒什么，但是使用你代碼的人會很關(guān)心這個?？紤]一下你想要用什么證書發(fā)布你的項目，務必選擇一個互聯(lián)網(wǎng)上的標準許可證。下一步做什么在你遵循上面的指南之后，我們相信你的項目將會成功。進一步的參考資料，查看這篇文章如何維護一個開源項目(/p/aaa2a5437d3a)。模板給你一個README的模板。如果你使用markdown的語法，把它命名為README.md。如果你使用reStructuredText的語法，把它命名為README.rst。$project========

$projectwillsolveyourproblemofwhere

to

startwith

documentation,by

providing

a

basicexplanationofhow

to

do

it

easily.

Lookhoweasyit

is

to

use:

import

project

#Getyourstuffdone

project.do_stuff()

Features--------

-

Be

awesome-

Makethingsfaster

Installation------------

Install

$projectby

running:

installproject

Contribute----------

-

Issue

Tracker:

/$project/$project/issues-

Source

Code