X12 精確地拆解、完全地對應(4)──記錄的內容

從寫計畫書時的拆解目標到記錄安裝手冊的步驟，最近感覺慢慢地開始喜歡撰寫文件。主要因為發現無論是目標的拆解或是一堆軟體的安裝，都是將許許多多的物與關聯運用平鋪直敍的方式來記錄；套用將人視為電腦的觀念，就像在制訂匯出的規範（決定匯出的順序與內容），讓匯出的資訊進到任何一個人都可以還原前人腦中的想法。

●第一個考慮的是全部的範圍。根據需要安裝的軟體、需要的環境設定、專案的參數定義與需要完成的特定事件來思考並加以歸類；未來每一個項目都要製作對應文件說明。在這裡可以想像是Use Case的定義與群組化，再加上循序漸進地順序佈置以建構閱讀者對整個平台的瞭解。

●對於每一個說明點的內容，意義上與用文字敍述的功能劇本差不了多少。準備的檔案與起始狀態、每一個步驟的忠實記錄並佐以圖檔、每一步驟後的狀態檢查、還有最後完成的狀態與驗證，都是需要記載於文件的內容。其中若有小目的需要用多個步驟才能完成，應加以群組起來說明較為清楚（很像是寫程式時將多行群組為一個方法）。

●有時會需要兩層式的文件才能說明一件事。例如建置一個Maven專案的流程要在Eclipse上新建Maven專案、設定subversion儲存庫再share project，倘使流程文件直接記錄每個步驟，就會發生其他流程要使用設定subversion儲存庫這個步驟的說明時，不知是要參照其中的步驟(只參考流程的一部分)還是自己建立新的說明（重覆的資料）好。我的解法是每個步驟都拆到對應軟體的操作手冊裡，再從流程內容參照過去；整個流程需要輸入的資料則記錄在流程文件裡，畢竟那是該流程特有的內容。

在移交開發平台的過程中，曾經為了兩個沒有記錄到的小步驟，用了一個工作天才感覺似乎少了些什麼，一天之後才確認真的有缺少。記錄兩個小步驟只是幾分鐘的時間，但是可以省下不應花費的一天；用這個例子提醒自己撰寫文件的價值與影響，自然會時常懷著戒慎恐懼的心態力求完整。