這是人月神話：軟體專案管理之道（20週年紀念版）的第十五章：一體兩面(The other face)，簡體版譯作另外一面，到是很直覺，而一體兩面四個字用起來很像是成語，不過譯的是否貼切，有待進一步觀察。ㄚ琪從頭到尾看完一遍，很抱歉看不出內容跟主題關聯的情形，倒是開場白歌德『What we do not understand we do not possess.』『我們無法主宰我們不瞭解的東西』，倒是滿貼切的，這一篇對ㄚ琪來說，是個很實用的建議，我應該會把裡面的教學做在我的程式裡頭。本篇的重點就是「如何」寫好文件。
該寫哪些文件？
為使用程式而寫的文件 這裡主要針對文件應該先有概觀性的描述(overview)，作法引用簡體版並譯成繁體字使用如下：
1. 目的。主要的功能是什麼？開發程式的原因是什麼？
2. 環境。程式運行在什麼樣的機器、硬體配置和作業系統上？
3. 範圍。輸入的有效範圍是什麼？允許顯示的合法範圍是什麼？
4. 實現功能和使用的演算法。精確地闡述它做了什麼。
5. 輸入－輸出格式。必須是確切和完整的。
6. 操作指令。包括控制臺及輸出內容中正常和異常結束的行為。
7. 選項。用戶的功能選項有哪些？如何在選項之間進行挑選？
8. 運行時間。在指定的配置下，解決特定規模問題所需要的時間？
9. 精度和校驗。期望結果的精確程度？如何進行精度的檢測？
這樣就可以寫出3到4頁的摘要性說明，這裡頭有些ㄚ琪還需要改善自己的文件說明，但是環境常常會省略掉，以後應該會加入進來。
為建立對程式的信心而寫的文件 這句話的意思就是增加測試案例(test case)，我倒是沒有寫這個文件的習慣，改吧。這種文件有三部份：主案例、罕見合法案例及罕見不合法案例。
為修改程式而寫的文件 包含的部份：
1. 流程圖或副程式的結構圖，對此以下有更詳細的論述。
2. 對所用演算法的完整描述，或者是對文件中類似描述的引用。
3. 對所用檔案規劃的解釋。
4. 解譯階段結構(pass structure)的概觀——從磁片或者磁帶中，獲取資料或程式處理的序列——以及在每個處理過程必須完成的操作。
5. 初始設計中，對已預見修改的討論；特性、可插入點(hooks)與離開點(exits)；原作者對可能會擴充的地方以及可能處理方案的一些意見。另外，對隱藏缺陷的觀察也同樣很有價值。
惱人的流程圖
這個流程圖到是很讓ㄚ琪頭痛，因為ㄚ琪從來沒有將流程圖做出來過，但是在看別人寫的程式時，卻又很希望作者有流程圖可以讓人參考，很矛盾吧，好在作者也不建議做流程圖，終於有跟ㄚ琪同一陣線的人了，給個讚，但是作者反倒建議將程式轉成以執行階段或步驟為主的結構圖，然後畫在一頁大小的流程圖上，倒是滿方便的，舉例如下圖：
這裡還引用使徒行傳15:10『現在為什麼試探神，要把我們祖宗和我們所不能負的軛放在門徒的頸項上呢？』，當然典故ㄚ琪就不多說了，只能說作者用聖經的話來強烈支持不做流程圖，ㄚ琪頗認同這觀點。
自我說明程式
這裡頭建議把書面說明寫到程式碼裡，這樣可以大幅改善維護工作，而且保證程式使用者可以隨時便利地參考文件，這種作法稱為程式的自我說明(self-documenting)，感覺好像Java的說明文件喔，很有可能是有這裡衍生出來的。
可行的方案
第一個想法是借助那些出於語言的要求而必須存在的語句，來附加盡可能多的“文件”資訊。因此，標籤、宣告、符號名稱均可以作為工具，用來向讀者表達盡可能多的意思。
第二個方法是盡可能地使用空格和一致的格式提高程式的可讀性，表現從屬和巢狀關係。
第三，以段落注釋的形式，向程式中插入必要的敍述性文字。
拒絕去做的理由 我想已經沒有理由了吧，Java都弄的嚇嚇叫了，甚至組合語言也可以這樣做吧，那就很cool了，不過這樣的文件如果有時來個範例說明，感覺就更好用了，當然這是以在學者的角度來看的。