iT邦幫忙

DAY 16
8

系統工程師該知道的31件事系列 第 16

系統工程師該知道的31件事(13_文件制作時...)

如果這個系列的上一篇,讓您看了不舒服或是感覺非常不好,Allen 利用這個機會,向您深深的道歉,『對不起,讓您看了後感覺不好』。鐵人賽的後半段,我會更加注意,從今天開始,我會先寫這個系列,再寫另一個系列。
如果平常沒有用工具軟體,在工作上輔助我們。如果對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」那我就該需要知道「主要閱讀者」最希望知道的是什麼,能幫助他什麼。

其實...我現在最想寫的文件,是『結婚企劃書』,「主要閱讀者」是我未來的老婆(羞)...

如果這個系列的上一篇,讓您看了不舒服或是感覺非常不好,Allen 利用這個機會,向您深深的道歉,**「對不起,讓您看了後感覺不好」**鐵人賽的後半段,我會更加注意,從今天開始,我會先寫這個系列,再寫另一個系列。

(待)

2012/10/09 太陽哲齡

更多文章都在行雲流水IT人

文章導覽
上一篇
下一篇
個人全系列連結


上一篇
系統工程師該知道的31件事(12_聽不懂、誰之過)
下一篇
系統工程師該知道的31件事(14_Google不是萬能)
系列文
系統工程師該知道的31件事37
0
pajace2001
iT邦研究生 1 級 ‧ 2012-10-09 00:29:50

沙發

在制作文件的時候,只有一個重點。這份文件「主要的閱讀者」是誰? 工作內容為何? 他希望看完這份文件後,能獲得什麼?

的確,閱讀文章的對象真的很重要!不然寫出來的東西對方看不懂也是白搭!我之前也常常犯這種錯誤XD

其實...我現在最想寫的文件,是『結婚企劃書』

先恭喜太陽大啦讚讚讚

0
海綿寶寶
iT邦大神 1 級 ‧ 2012-10-09 07:32:41

sunallen提到:
每次只要先寫『工程師復愁記』再寫『工程師該知道的31件事』,我就像是「小四附身」

我就說嗎
雙修很辛苦的
忙

sunallen提到:
這樣的文件,對方大概看了三、四頁,就不會想繼續看下去了。

奧客守則第14條「不要接受乙方文件的第一個版本」
奧客守則第15條「不必看,直接退回」
奧客守則第16條「第三個版本後再考慮開始看內容」
嘆氣

citysam iT邦新手 2 級 ‧ 2012-10-09 09:10:14 檢舉

antijava提到:
我就說嗎
雙修很辛苦的

對啊,共修比較好啦.................溜

ted99tw iT邦高手 1 級 ‧ 2012-10-09 09:16:10 檢舉

大家加油用力修啦,不用理俺這個.....老不修~~無言

0
oowo
iT邦高手 1 級 ‧ 2012-10-09 08:14:17

通常寫文件要注意的我只記得一件事...
把對方當成不懂的人下去寫就對了....
雖然說這樣文件會很長,可是...最少你可以省的有人問東問西的
我是這樣想的…

0
louis1w
iT邦新手 3 級 ‧ 2012-10-09 08:17:46

其實...我現在最想寫的文件,是『結婚企劃書』

我也要看 想看想看

0
magician
iT邦研究生 2 級 ‧ 2012-10-11 09:29:00

『結婚企劃書』

快寫快寫~~~我會負責揪出問題點~嘿嘿

0
yidchenlily
iT邦新手 5 級 ‧ 2018-03-19 13:42:46

這個系列給我很大的啟發,
雖然有幾篇筆鋒稍微尖銳,
但是我好喜歡您文字的溫度,一語點醒夢中人。
為了能表達我的謝意,辦了這個帳號,也才知道您有這麼多文章,
謝謝您的分享。

--IT小小小菜鳥

SunAllen iT邦研究生 1 級 ‧ 2018-03-22 22:16:32 檢舉

/images/emoticon/emoticon41.gif

謝謝您!

我要留言

立即登入留言