這是一篇幫助你給第一個項目寫文檔的指南。

萬事開頭難，我希望這份指南能把你引導到正確的道路上。

最后，你應該有一個可以公開發布的項目。

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

為什么要寫文檔？

你將會在 6 個月后使用你的代碼

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

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

你想要別人使用你的代碼

你已經寫了一段代碼，并且發布了它。你這樣做是因為你認為別人可能覺得它有用。但是，人們需要先知道為什么你的代碼對他們可能有用，才會決定使用它。文檔可以告訴人們這個項目對他們有用。

如果人們不知道你項目存在的意義，他們不會使用它。

如果人們不知道怎么安裝你的程序，他們不會使用它。

如果人們不知道怎么使用你的代碼，他們不會使用它。

只有少數人會深入研究你的代碼并且使用它。幾乎沒人會使用你的代碼，除非它有好的文檔。如果你真的熱愛你的項目，給它寫文檔，讓其他人使用它。

你需要別人的幫助

開源項目是具有魔力的，對嗎？你發布了代碼，然后 code gnomes 出現并且讓你的代碼更好。

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

我創造了價值！

如果它出錯了怎么辦？！

我是一個開源項目開發者了！

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

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

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

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

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

實際上，不完全是這樣。

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

在你為項目付出大量工作之后，才能獲得貢獻。

在你的項目有用戶之后，才能獲得貢獻。

在你的項目有文檔之后，才能獲得貢獻。

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

文檔讓你的代碼更好

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

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

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

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

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

用什么工具寫作

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

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

純文本版本控制

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

基本例子

1

2

3

4

5

Resources

---------

*Online documentation:http://docs.writethedocs.org/

*Conference:http://conf.writethedocs.org/

上面的文字將渲染成標題，下面帶著列表。URLs 將會被自動超鏈接。這寫起來很容易，不但作為純文本有意義，而且還能很好的渲染成 HTML。

README

你第一個應該寫的文檔是 README。如果你提供了合適的擴展名，代碼托管服務會自動把你的 README 渲染成 HTML。它也是大多數用戶跟你的項目的第一次互動。所以，一個可靠的 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。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

$project

========

$project will solve your problem of where tostart with documentation,

by providingabasic explanation of how todoit easily.

Look how easy it istouse:

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

-------

Ifyou are having issues,please let us know.

We haveamailing list located at:project@google-groups.com

License

-------

The project islicensed under the BSD license.

總結

以上是生活随笔為你收集整理的python开发技术文档范文_程序员编写技术文档的新手指南的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。