如何編寫Python軟體開發文檔

開發文檔是經常被程式員忽略的工作，有時也會被管理者忽略。這往往是由于在項目生命周期結束的後期缺乏時間，以及人們認為自己不擅長寫作，其中一些人确實寫不好，但他們中的大多數能夠完成一個良好的文檔。

在任何情況下，匆忙編寫文檔的結果是文檔會變得一團糟。大多時候，開發人員讨厭做這種工作，尤其當現有文檔需要更新時，情況會更糟。因為經理不知道如何處理更新，許多項目隻是提供簡陋而又過時的文檔。

編寫良好的文檔在許多方面比編寫代碼更容易，大多數開發人員認為這很難，但通過遵循一組簡單的規則，它會變得非常容易。

本節給初學者介紹了 7 條應該遵循的規則，可以應用在所有情況下，讓編寫開發文檔事半功倍。

1) 專注于想法，然後審查和塑造你的文本

要知道，幾乎沒有人在第一次就寫出完美的開發文檔，因為多數人在編寫文檔時都嘗試一次性将文檔編寫到完美，為此他們每寫兩句就停止寫作，然後閱讀他們并做一些修正。這意味着，他們将重點都放在文本的内容和風格上。

這種編寫方式的結果往往沒有預期的那麼好，原因很簡單，人們在還沒有想清楚要寫的内容之前，就将大量的時間和精力花在修正檔案的風格和形狀上。

我認為，正确的編寫方式應分為 2 步，第一步無需考慮文本的風格群組織，專注于編寫文檔的内容。注意，最好能夠将所有的想法都寫在紙上，至于怎麼寫先不考慮。

也就是說，第一步的重點就是打造内容，隻要不是關于内容的問題（例如文法錯誤等），都不需要關心。

通過這種方式，開發者能夠專注于他的想法，并且可能會從想到更多的内容，而不隻局限于其最初的想法。注意，在編寫過程中，很容易在頭腦中一閃而過一些想法，當它們出現時，比較好的的做法是将它們寫到紙上，寫完後可以繼續回到目前的寫作中。

第二步就是回讀整個文本并對其進行修正，以便每個人都能了解。修正文本意味着要增強其風格，糾正其錯誤，重新組織它，并删除任何備援的内容。

總之，當編寫開發文檔的時間有限時，比較好的做法就是将可利用的時間一分兩半，一半用于寫作，一半用于清理群組織文本。

2) 準确定位讀者

編寫開發文檔時，首先應該考慮清楚，誰會讀這個文檔？

千萬不要認為定位讀者很簡單，因為開發文檔解釋了一個軟體如何工作，并且通常為每個可能擷取和使用代碼的人而寫，讀者可能是正在尋找問題的合适技術解決方案的研究員，也可能是需要利用其實作特性的開發者，甚至架構師，也可以從架構的角度來看它是否符合需求。

是以，好的開發文檔應該遵循一個簡單的規劃，即每個文本應該隻針對一種類型的讀者。而這也使編寫文檔更容易，因為我們可以準确地知道面對的是什麼樣的讀者。

另外，開發文檔中最好提供一個簡短的介紹性文本，用來解釋文檔是什麼，并知道讀者去讀他感興趣的部分。

3) 讀者更喜歡簡短的句子

對于絕大多數讀者來說，往往更喜歡短而簡單的句子，而不是長篇大論的段落。

使句子短而簡單的方法有如下幾個：

• 每個句子不應超過 2 行；
• 每一段應隻表達一個主要思想，最多包含 3 到 4 個句子；
• 每個想法的解釋不要重複太多，避免像新聞那樣一再重複，隻要保證讀者能夠了解即可。
• 如果你不是一個真正優秀的作家，避免在文檔中講笑話，因為在技術文檔中添加滑稽的語言是很難的，很少有人掌握它。如果你想添加一些幽默，可以将它們放到代碼示例中。

4) 撰寫貼合内容的标題

不好的軟體開發文檔幾乎都存在一個問題，即我們知道文檔中包含自己要找的資訊，但卻要花很長時間去找。當作者沒有将它們的文本内容合理地組織到标題中時，就會出現這種情況。

是以，建議大家在編寫開發文檔時，将段落聚集在給定章節的有意義的标題下；整個文檔的标題可以用短語來組織；文檔的目錄可以由所有章節的标題組成。

總之，撰寫标題最簡單的做法就是問自己：“在百度中輸入什麼短語才能找到此部分内容”？

5) 文檔中應使用項目中的代碼作為示例

當讀者試圖通過一個使用示例來了解一段代碼如何運作時，不切實際的示例代碼往往更讓人難以了解。

舉個例子，假設我們想要展示如何使用 parse() 函數：

fromatomisator.parserimportparse
#用法如下：
stuff=parse("some-feed.xml")
stuff.next()      

輸出結果為：

{'title':'foo','content':'blable'}      

更好的例子應該是，讓解析器知道如何使用解析函數傳回一個 feed 的内容，可作為一個頂級函數使用，如下所示：

fromatomisator.parserimportparse
#用法如下：
my_feed=parse("http://tarekziade.wordpress.com/feed")
my_feed.next()      

輸出結果為：

{'title':'eight tips to start with python','content':'The first tip is ..., ...'}

這個微小的差距可能有點過分誇張，但實際上它能夠使文檔更有用，讀者可以将這些代碼行複制到一個 shell 程式中，了解 parse 将使用一個 URL 作為參數，并且傳回包含部落格條目的一個枚舉型變量。

總之，文檔中使用的代碼示例應該在實際的程式中直接可用。

6) 文檔内容以實用為主

其實，軟體開發中所用的大部分方法，是不需要用文檔進行說明的，相比更詳盡的文檔，使軟體正常工作無疑更重要。是以，一個好的做法是隻編寫真正需要的文檔，而不是編寫一個詳盡的文檔集。

舉個例子，對于管理者來說，隻需在文檔中說明軟體是如何工作的就足夠了，他們除了要知道這個工具的配置和運作方法之外，沒有其他的需求。是以，這個文檔應将範圍限制"如何在自己的伺服器上運作軟體"。

可以運作的軟體，遠遠勝過面面俱到的文檔。

7) 使用模闆