若問為何如此，大概是因為大部份人（特別是技術人員）都把撰寫文件視為厭惡性的工作吧。
故此有些公司會找專責的人員寫文件，有時會是technical writer，有時則是manager、也有機會找Marketing/sales代勞 ﹣ 因為那是客戶要求的東西，至於是否能反應實際情況.... 天知曉。
而沒有專責人員的公司.. well.. 沒有文件是很平常，有時候更會鬧出笑話。
話說在某U公司，曾經聘請了某內地高手C開發了一件硬件產品，這產品會用於某系統上，完成後則連整個系統交付了給第一位客戶，然後就離職了，他所留下的只有線路及firmware的binary，還有一份難以理解的protocol文件。
後來要把這件產品裝嵌在另一個系統上，新晉的工程師B無法理解這是什麼鬼東西，沒有說明文件，那就自己去研究這東西是做什麼的吧，理解是理解了，不過沒有規格，所以根本不知道能力的上下限在那裹，更甚至他認為這東西其實是廢物來的，只要買個Programmable Logic Controller回來就有等效的能力，而且更平宜。
及後C回巢，B立即提出要求C補回當年的文件，殊不知老闆D與C其實是很要好的朋友，這東西本來就是他們聯手想出的「偉大構思」，基於C又是一位極度厭惡寫文件的人，而又獲得老闆的特別照顧，結果D就異想天開地想出一個方法，就是由D本人開班授徒，把這「偉大的構思」教給其他工程師，再由這些工程師去補寫文件。
那天除了D以外，還有一位manager及四位工程師。
粗略以老闆50k、manager 30k及各工程師17k的人工計算，假設22個工作天，這份大概30多頁紙的文件就得花上近7千元港幣的代價（相信已經低估了這班人的人工），而且故事也沒那麼順利，因為老闆D根本就不懂.....花了一天講的都不過是他所猜度的內容，最後另一位工程師A費了很大的勁力才真的弄出了一份文件。
這個故事告訢我們
這種完全不寫、寫不出文件的人並不是十分罕見，在某些地方會經常遇到，不過主要的原因不是出於腦子有文字處理的困難，實質是為了保障自己的措施，為了讓僱主難以把他開除才故意寫不出來。
雖然一般的Programmer大多討厭寫文件，但到底討厭的是寫冗長的文件、還是真的連半點文字都寫不出來呢？老實說後者實在不太可能，這可能要去看一看醫生了，所以真正討厭的是寫沉長、甚至沒人看的文件 － 筆者也怕寫這種文件
不會因此就連半點文件都不寫就是非專業所為了，最低限度如規格、時程、編譯指南、簡短的使用方法等還得由programmer撰寫。
Programmer的本職畢竟不是文字上的寫手，花費過多的時間在文件上會反而影響開發的進度，而且也會讓他們卻步。
故問題是怎樣降低花上文件上的時間而又能維持一定的質素，筆者的建議是collaborative writing（協同寫作），別要一個人把整個系統的文件寫出來，而是各人分工寫不同的部份，然後再檢閱其他有關模組的文件（這通常是由別人寫的），再提出意見、修定，互相彌補不足之處。
首先要文件寫得淺白而懂、連麻瓜都看得懂等的要求拋棄，他們想看的其實是Harry Patter，但你可不是J·K·羅琳；你是一名專業的工程師，這表現在資料的詳盡程度及內容編排上，有需要的也得提供圖片。
然後你要
- 擔當一名有限能力的寫手，寫出自己負責的部份的文件，再拜託其他同事幫忙校對。
- 同時擔當一名副業的校對人員，查閱跟自己有關的文件並提出意見，有需要時會自行修改。
把以上寫、校對的過程重複幾次，一份詳盡而又足夠讓技術人員明白的文件就會誔生。
至於是否一份讓管理層贊賞的文件……？well，別做多餘的事。記得在大學工程學院讀書時，technical writing那課特別強調文件要寫得淺白易懂、更要讓麻瓜也看得明白…………這是嚇壞programmer的原由之一吧！
真的是弄出針對一般人看的文件，不如直接請個專責的technical writer吧！
別要求programmer當作家，他們的責任應當是提供一切需要的資訊，讓文字美化的工作需找其專責的人員舉一個例子。
在筆者任職過的某公司，要用某嵌入式平台進行開發，包括筆者在內沒有任何人有過這平台的經歷，故找了某君當前鋒摸索，那時筆者要求他把結果寫成文件，而他立即面露難色。
筆者就降低要求，只需要把打過的指令及使用的檔案例出來，文件的第一版很快就完成了。
然後筆者跟著這份文件設定環境，過程中加上適當的指示，有無法進行的步驟則要求原作者補充，花了點時間終於完成了第二版的文件，其他同事就依第二版文件進行設定，大部份都能立即上手。
後來要讓其他部們的人也跟著做，基於專業有異，第二版的文件他們有許多地方看不懂，收集了他們的疑問後弄出了第三版 － 那是連非這個專業的人都能照著做的文件。
雖然時間長了一點，不過協同寫作對所有人的壓力都是最低的，可以讓programmer更樂於從事文件的寫作。
要做到協同寫作，最簡單的方法莫過於使用wiki，概可讓多人同時寫作，又有版本控制，追蹤修定也非常的簡單。
Wiki的好處：
- 協同寫作
- 版本控制
- 搜尋簡便
相關閱讀
沒有留言:
發佈留言