開發文件是經常被程式設計師忽略的工作，有時也會被管理者忽略。這往往是由於在專案生命週期結束的後期缺乏時間，以及人們認為自己不擅長寫作，其中一些人確實寫不好，但他們中的大多數能夠完成一個良好的文件。
在任何情況下，匆忙編寫文件的結果是文件會變得一團糟。大多時候，開發人員討厭做這種工作，尤其當現有文件需要更新時，情況會更糟。因為經理不知道如何處理更新，許多專案只是提供簡陋而又過時的文件。
編寫良好的文件在許多方面比編寫程式碼更容易，大多數開發人員認為這很難，但通過遵循一組簡單的規則，它會變得非常容易。
本節給初學者介紹了 7 條應該遵循的規則，可以應用在所有情況下，讓編寫開發文件事半功倍。
1) 專注於想法，然後審查和塑造你的文字
要知道，幾乎沒有人在第一次就寫出完美的開發文件，因為多數人在編寫文件時都嘗試一次性將文件編寫到完美，為此他們每寫兩句就停止寫作，然後閱讀他們並做一些修正。這意味著，他們將重點都放在文字的內容和風格上。
這種編寫方式的結果往往沒有預期的那麼好，原因很簡單，人們在還沒有想清楚要寫的內容之前，就將大量的時間和精力花在修正檔案的風格和形狀上。
我認為，正確的編寫方式應分為 2 步，第一步無需考慮文字的風格和組織，專注於編寫文件的內容。注意，最好能夠將所有的想法都寫在紙上，至於怎麼寫先不考慮。
也就是說，第一步的重點就是打造內容，只要不是關於內容的問題（例如語法錯誤等），都不需要關心。
通過這種方式，開發者能夠專注於他的想法，並且可能會從想到更多的內容，而不只侷限於其最初的想法。注意，在編寫過程中，很容易在頭腦中一閃而過一些想法，當它們出現時，比較好的的做法是將它們寫到紙上，寫完後可以繼續回到當前的寫作中。
第二步就是回讀整個文字並對其進行修正，以便每個人都能理解。修正文字意味著要增強其風格，糾正其錯誤，重新組織它，並刪除任何冗餘的內容。
總之，當編寫開發文件的時間有限時，比較好的做法就是將可利用的時間一分兩半，一半用於寫作，一半用於清理和組織文字。
2) 準確定位讀者
編寫開發文件時，首先應該考慮清楚，誰會讀這個文件？
千萬不要認為定位讀者很簡單，因為開發文件解釋了一個軟體如何工作，並且通常為每個可能獲取和使用程式碼的人而寫，讀者可能是正在尋找問題的合適技術解決方案的研究員，也可能是需要利用其實現特性的開發者，甚至架構師，也可以從架構的角度來看它是否符合需求。
因此，好的開發文件應該遵循一個簡單的規劃，即每個文字應該只針對一種型別的讀者。而這也使編寫文件更容易，因為我們可以準確地知道面對的是什麼樣的讀者。
另外，開發文件中最好提供一個簡短的介紹性文字，用來解釋文件是什麼，並知道讀者去讀他感興趣的部分。
3) 讀者更喜歡簡短的句子
對於絕大多數讀者來說，往往更喜歡短而簡單的句子，而不是長篇大論的段落。
使句子短而簡單的方法有如下幾個：
-
每個句子不應超過 2 行；
-
每一段應只表達一個主要思想，最多包含 3 到 4 個句子；
-
每個想法的解釋不要重複太多，避免像新聞那樣一再重複，只要保證讀者能夠理解即可。
-
如果你不是一個真正優秀的作家，避免在文件中講笑話，因為在技術文件中新增滑稽的語言是很難的，很少有人掌握它。如果你想新增一些幽默，可以將它們放到程式碼範例中。
4) 撰寫貼合內容的標題
不好的軟體開發文件幾乎都存在一個問題，即我們知道文件中包含自己要找的資訊，但卻要花很長時間去找。當作者沒有將它們的文字內容合理地組織到標題中時，就會出現這種情況。
因此，建議大家在編寫開發文件時，將段落聚集在給定章節的有意義的標題下；整個文件的標題可以用短語來組織；文件的目錄可以由所有章節的標題組成。
總之，撰寫標題最簡單的做法就是問自己：“在百度中輸入什麼短語才能找到此部分內容”？
5) 文件中應使用專案中的程式碼作為範例
當讀者試圖通過一個使用範例來理解一段程式碼如何執行時，不切實際的範例程式碼往往更讓人難以理解。
舉個例子，假設我們想要展示如何使用 parse() 函數：
from atomisator.parser import parse
#用法如下：
stuff = parse("some-feed.xml")
stuff.next()
輸出結果為：
{'title':'foo','content':'blable'}
更好的例子應該是，讓解析器知道如何使用解析函數返回一個 feed 的內容，可作為一個頂級函數使用，如下所示：
from atomisator.parser import parse
#用法如下：
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) 使用模板
以維基百科為例，你會發現它每個頁面的布局都是相似的，一側有用於總結日期或事實的文字方塊，文件開頭總有一個目錄（包含該頁面中的所有標題的連結），文件結尾處總有一個參考部分，等等。
使用維基百科的使用者習慣了這個頁面的佈局，例如他們就可以快速檢視每個頁面的目錄部分，還可以快速檢視參考文獻等等，固定的結構布局會提高使用者的效率。
所以，使用模板強制文件安裝固定的模式，可以使使用者更高效地使用它們。