系統工程師該知道的31件事(13_文件制作時…)
如果平常沒有用工具軟體，在工作上輔助我們。如果對26個英字母非常不熟悉。如果感覺到一堆指令是一場惡夢、錯綜複雜的系統是一團迷霧。那寫文件時，就很像是在地獄。
今年我寫的文件總數，比2001到2011年加起來的還要多，除了用可怕之外，更難受的是寫完後被退回、寫完後被退回…像個有條件的迴圈，不斷的在那迴圈裡面打轉。如果用簡單語法描述，就像下面的範例：
Do until 客戶&教授滿意
內容修改
Loop
加了教授滿意，是因為去年到今年上班年也同時在寫論文，專案要交付的文件和論文要完稿的日期，差不多都在同樣的時間，特別是專案要交付的文件，和驗收要交付的文件，來來回回，改了好幾十次…有人問我「為什麼你不一次就寫到好? 讓客戶看了滿意?」
那是一個理想，但有時候我們要交付的文件，就像程式設計師寫出來的程式、美工編輯畫出來的圖形、網頁開發人員所做出來的版型，都是從不斷被退回中，慢慢長 大，最後成形。原因是…第一版還沒出現時，客戶都是先憑空想像…看到文件第一版後，看到實際的內容後，再提出需要修正的地方，這時候第二版就出現 了。
有的時候，第二版還沒完成，客戶就提升了自己對產品的熟悉度或是從第一版中，找出了嚴重的錯誤，因此第二版出來後，客戶看了，發現有少了什麼部份或是描述 不整的狀況，一定會要求再改，改到第三版。然後，就開始進入「滿意迴圈」，甚至對於文件中所使用的「文字」都會特別要求。
在過去制作的文件中，有段文字，原先是這樣寫的。
『當服務啟動之後，這個服務，所使用的網路port就會被開起，並進入Listen狀態。』
客戶看完後，問我「一定會開起嗎? 一定會進入Listen嗎?」
我想了一下，回答『不一定耶，如果服務啟動有錯誤的話，如果設定檔沒有設定要開的port…要使用的port就不會被打開，也不會進入Linsten。』
客戶聽完後，告訴我「看吧! 你寫的還不夠完整，你應該要列入各種狀況，把所有可能都寫進來，不能只寫「正常」的情況。」
聽到這些，我就傻了。我連自己筆電裡的Windows 7，內建的功能和指令，都沒「全部」用過…怎麼可能寫出一份，針對某套企業級軟體的所有功能和所有狀況呢?
說實話，剛開始我接收到這樣的訊息時，非常不以為然，甚至覺得…『那不然你來寫啊，看看你能寫的多完整。』但，實在是要感謝當時的我，也在寫論文。我 記得論文被退回來的那天，教授跟我說「你的內容…有些地方不清不楚，數據沒有、佐證沒有、引用文獻沒有，這樣你會連畢業這檔事，都沒有哦。」
接著，我拿著被退回來的論文，給我母親看。我母親翻開第一章的第一頁…就問了我大概八、九個問題，外加挑出幾個錯字。那當下，我才驚覺，我犯了「自以 為是」及「角度問題」的嚴重錯誤。我仔細看了看已經交給客戶的文件，把內容不清楚、附圖、表不清楚的的地方，全部砍了，砍完之後的好幾個晚上沒睡覺，全部 重寫。
再交出去後的一個星期，客戶跟我說「你很用心哦! 很多地方都重寫了，而且比之前更清楚，連可能發生的狀況，也有提出相對應的程序去處理…你要不要全部重寫啊!?」
寫文件最怕的就是發生『整份文件裡面的內容，每一頁都有讓客戶看不懂或是客戶能指出，與實際狀況不符的地方，這樣的文件，對方大概看了三、四頁，就不會想 繼續看下去了。』今年上半年的某一天，開文件審查會議，我的文件被審了約三個小時，那三個小時鐘，我像是被釘牆上，除了我之外的與會者，輪流炮轟，不是內 容不夠詳細，而是章節順序不對、描述讓人搞不清楚之類的…
這一次的「系統工程師該知道的31件事」至目前，在站上前輩大大們提醒後，我發現我又犯了「角度問題」和「自以為是」的毛病，這些都圍繞在『基礎」這件事情上。
我未來的老婆，曾經跟我說「你在這行業幾年? 你們的新人同事幾年? 你怎麼可以用那麼多年的經驗，去評論一位新人? 你當新人的時候，有比對方好嗎?」
現在想起來，我的選擇是對的! 她都說對了，我還是菜鳥的時候，的確跟之後我所遇到的新人同事，都差不多一個樣。儘管這個系列的本意，是希望新進同業們，能減少、加速或避掉一些會遇到的 風險，但今天仔細看了上一篇「系統工程師該知道的31件事(12_聽不懂、誰之過)」的內容，我發現我有點「小四附身」。
「小四」是今年鐵人賽IT人生組『工程師復愁記』中的主角，在設定上，他是一位性格扭曲、凡事皆看不順眼，又不善良的反派，因為報名兩組，每次只要先寫 『工程師復愁記』再寫『工程師該知道的31件事』，我就像是「小四附身」，因為自己還沒有從「小四」的情緒及角度中脫離出來，就繼續寫另一個系列的文章。
而這，就是先前提到的「自以為是」和「角度問題」。
在制作文件的時候，只有一個重點。這份文件「主要的閱讀者」是誰? 工作內容為何? 他希望看完這份文件後，能獲得什麼? 如果我寫的是「Install Windows 2008 on IBM x3650 M2」那我就該需要知道「主要閱讀者」最希望知道的是什麼，能幫助他什麼。
其實…我現在最想寫的文件，是『結婚企劃書』，「主要閱讀者」是我未來的老婆(羞)…
(待)
2012/10/09 SunAllen
