程式設計師如何寫出乙份好的文件？

在實際的軟體開發工作中，除了編寫**之外，程式設計師還會花大量的時間來編寫相關的研發文件，這些文件包括：詳細設計文件、單元/整合測試文件、軟體版本開發報告、軟體安裝說明、軟體公升級指導書等。

在《程式設計師既要寫好**，又要寫好文件》(一文中，我提到過：「**」和「文件」就像是乙個人的左膀右臂，一定要讓兩者均衡發展，而不能夠只顧其一。既然文件這麼的重要，那麼對於程式設計師來說，我們如何才能寫出乙份好的文件呢？根據我個人的經驗，我們不妨從以下方面入手：

第一，將重要的內容分點描述，而不是雜糅在一起。

例如，有一段描述某軟體功能的話是這樣的：

我們可以看到，上面那段話將軟體功能描述放到乙個段落中，讀起來讓讀者雲裡霧裡的。我們可以把內容分點描述，如下：

該軟體模組在系統中占有重要的地位，其實現的主要功能為： (2)從本地目錄中獲取檔案進行解析，並生成新的檔案放到本地的另一目錄中。 (3)將目錄中生成的檔案上傳到客戶指定的ftp目錄中。 (4)清理本地目錄中的過期檔案(清理時間及過期期限可配置)。

這樣修改之後，文章的邏輯更加的清晰，可讀性更強，讀者也更容易理解作者所要表達的意思。

第二，將流程性比較強的內容畫成流程圖，而不是僅用文字描述。

一篇**並茂的文章才是好文章，如果大家看到一篇好幾十頁的文章全是文字，很容易失去閱讀的興趣。對於某些流程性比較強的內容，如果將文字變成流程圖，則給讀者的感覺是不一樣的。

例如，下面一段文字描述了socket的整個訊息流程：

第一步，建立socket。第二步，繫結指定的ip位址和埠。如果繫結失敗，則跳到第一步。第三步，啟動監聽。如果沒有監聽到訊息，則程式一直處於監聽狀態；如果監聽到了訊息，則執行下一步。第四步，迴圈從監聽佇列中獲取訊息，並根據訊息內容執行相關的操作。

將文字內容畫成流程圖，如下所示：

從流程圖中，我們更容易看出程式的邏輯，讓讀者在一段輕鬆的閱讀旅程中理解作者所要表達的意思。

第三，將帶數字的內容以圖表的形式呈現，而非用文字描述。

今年3月份，解決的軟體bug數量為8；今年4月份，解決的軟體bug數量為6；今年5月份，解決的軟體bug數量為10。

可以將以上內容替換成下面的圖表：

從圖中，我們更容易看出前後數字的變化情況，對所描述事物有乙個整體的把握。

第四，盡量不要直接在文件中貼**，而換之以偽**、流程圖等形式。以上幾點寫文件的建議是本人在寫文件過程中的一些心得體會，不見得都正確，大家可以參考。總的說來，文件的編寫要遵循簡單易懂的原則，要用最直接明了的方式來表達作者本人的意思。

愛因斯坦曾說過：「科學家應該使用最簡單的手段達到他們的結論，並排除一切不能被認識到的事物」。也就是說，簡單就是美。這個「簡單」的原則同樣可以應用到文件編寫中，應用到所有的軟體開發專案中。