2010年12月29日 星期三

文件撰寫的重要性(The Advantage of Keeping Records)

對於IT人來說,看文件、學技術,或者是透過別人的經驗分享,快速找到問題的解決方式,我想應該已經是家常便飯,不過從別的角度來看,其實對於技術人員來說,寫文件也是一件相當重要的事情,因為技術人員通常也都是技術本位,往往會讓開發出來的東西變得比較不人性(說得好聽叫:「技術本位」,說得比較糟就會變成:「難搞自以為是」的產品開發),其實先前在看一本源自對岸的《走出軟件作坊》的繁中版《走出軟體工場》時,裡面對於文件撰寫的描述,其實也點明了其重要性,我想不僅僅是軟體本身,就算是一個簡單的網路服務,我想撰寫文件其實都可以讓技術人員發現更多自己的盲點,或者是平常在開發時沒有想到的事情。

但是,話說回來,其實文件撰寫或許還是交給專業的人來執行,寫出來的東西比較能夠簡單易懂,至於工程師是否得要親力親為,其實也沒有一定的限制,不過以時下精簡的工作環境來看,其實每個IT的技術人員或多或少都會得要自己撰寫一些文件,小到某個功能的解說,大至整個架構或是產品開發的一些門檻,只是在這其中還是有很多值得反覆咀嚼的東西存在。

其實像我自己寫部落格,也算是一種文件的存在,而在產出文件(章)時並沒有什麼太大的門檻,唯一要注意的就是:「你想要表達的是什麼?並且給看?」(老實說我也還在努力學習中)

閱讀文件的對象決定一切

自己:

對於平常有寫日記的人來說,想要寫出自己的心路歷程,或者是寫下某個案子中自己所扮演的角色,應該不是一件難事才對,因為寫出來的內容就算再無章法,自己也依然能夠循得一定的脈絡來閱讀(當然也是有些自己寫完之後,自己看不懂在寫什麼的奇才存在),不過那畢竟是少數。

不過也因為如此,通常對於自己撰寫的文件,往往會較為馬虎,所以很容易變成流水帳,未來在尋找一些資料或是急需某些關鍵步驟的內容時,就得面臨大海撈針的情況,所以就算是寫給自己看的文件內容,有機會的話還是可以分享出來讓別人檢視,在這過程中你往往會發現到自己的不足,甚至他們會引導自己寫得更好、更有效率。

同事:

對於要寫給一起工作的同仁的文件,可能遠比寫給一般大眾的文件還要困難,你一定心裡會想:「不是因為同事,更能夠瞭解彼此的工作內容跟屬性嗎?」,其實那都是在理想的狀況之下,更多情況是:「因為瞭解對方的工作內容,往往帶著更多偏見...」,其實這就跟辦公室文化一樣,每個人都無法感同身受其它部門的辛苦,往往都會有先入為主的觀念存在。

這時在撰寫給同仁間閱讀的文件時,往往得要因人而異地避開許多內容,但是又不能夠失去應該要表達的內容,這時候撰寫文件的人就會覺得自己會得人格分裂,同時還得要拿捏用詞,以免招惹到不習慣被文字侵犯的主管們,所以我才說寫這種文件,往往比寫給什麼都不知道的一般人更難下筆。

主管:

如果是下對上的文件,其實要寫的內容反而簡潔許多,因為通常主管看文件都是抓重點看,所以適當的標出重點是不可或缺的功課,不過,這不代表你可以隨便寫,該比較的圖表佐證的資料,以及自己對於某些情勢的判斷解讀都不可少,因為主管雖然不一定會細細品味你在文件中所寫的全部內容,只要他關注的東西一旦沒有在你的文件中備齊,你就可以有機會看見文件會被駁回重寫,而且通常也不會告訴你那邊有問題

除此之外,其實在寫文件時的細心程度也相當重要,有時候錯別字或是贅字,都會讓主管對於你的信任度下降,同時也代表著你在執行專案時,可能會有狀況發生的前兆,雖然我們知道沒有完人的存在,但是也千萬不要以為自己某些業務執行的能力很強,就可以其它什麼事都可以不用會,這往往是照成整個組織運作的極大損害,更別忘記在老闆的眼中:「沒有什麼人是不可取代」的鐵律。

一般大眾:

要寫個一般大眾看的內容,不外乎就是操作手冊或是使用說明,這一種類型的文件,只要通俗,並且實際反應出「正常」操作時所需的注意事項即可,其實可以去找找歐、美同類型產品的使用說明(其實西方真的在這一點,做得比我們出色許多),其實很快就能夠抓到一些要訣,同時要注意少用專有名詞或是不適當的縮寫。(我個人也很納悶究竟是誰創了這麼多英文縮寫呢?)

其它的部分就是親自實際去操作一次,最好也能夠去參考一下別人同類型的產品或平台,千萬不要憑著既有印象來撰寫這一類的文件,因為印象是會騙人的,而且一般使用者會發現的缺點,絕對會比你想像中的多出許多,如果你能夠在使用者發現之前,就能夠婉轉地告訴使用者這些缺點該如何克服,或者是提出較為中肯的解釋,我想這份文件就已經達到大半的功用。

其它的部分就是減少使用者打來詢問問題的可能性,同時也可以減緩不必要的人力支出,更不用說可能帶來不好的使用者體驗,這些都算是使用說明文件的隱性優點,不過很可惜,因為產品不同,對於時效(上線)的即時性也不同,這部分就是最常被忽略的小事,經常會轉變成未來可能得要付出更多心力的大事,端看主導者如何衡量輕重。

無論你是一個快速開發產品的高手,還是一個主導產品是否能夠準時上線的專案經理(主管),或許每天醒來都是要跟時間賽跑,不過,在往前衝的同時,千萬不要忘了回頭鞏固已成型的基石,說不定,那才是有機會能夠撐下去比氣長的關鍵,而不是一昧地在比誰先搶登那個山頭,畢竟山頭過後是懸崖,還是另一座高峰,也決定在自己如何看待它的態度。