幾度夕陽紅

如何撰寫技術文件

改善技術文件的品質，是新工作的任務之一，我打算在上任前先做點功課，喝過今天的第一杯咖啡，上網找了些相關資料，正巧 ReadWriteWeb 的作者Audrey Watters上週發表了一篇短文： Tips for Writing Good Documentation，簡明扼要的介紹了撰寫技術文件的觀念，但沒有涉入太多細節，看來是不錯的起點。

確認文件的讀者是誰，是 Audrey Watters 談到的第一個基本觀念，不論是平面的文字還是立體的簡報，目的都是「傳達」某些訊息給受眾（ audience），所以了解文件的目的，弄清楚讀者的知識背景、偏好的 接收訊息方式，都是製作文件前最基本、必要的前置作業。可是，真正落實這個「大家都知道」的觀念，踏實做準備功課的撰稿人，並不太多！

接著Audrey Watters介紹Django共同開發者Jacob Kaplan-Moss的Writing Good Documentation系列文章，Jacob 把技術文件分為三大類：Tutorial、Topial Guide 和 Reference Guide，每種文件類型有各自不同的目的和重點，然後 Jacob 在 Technical Style中介紹了他認為值得推薦的學習路徑，以及參考書籍（作者考慮的是用英文撰寫文件的情形，如果是用不同的語言撰寫文件，參考書籍必然要因地制宜做修改），最後他談到什麼是比較理想的文件風格（Style）。

Jacob 關於風格的建議可從兩個角度來分析，一個是老貓常提到的易讀性的考量，比如說字型、行距、空間配置等等，另外一個角度則是敘事說理的文字表達方式的考量。前者考慮的是讓讀者看的「舒服」，讀者閱讀技術文件的目的不外乎吸收知識或是解決問題，什麼樣的版型、字型配置，能讓讀者迅速找到他需要的資訊，是技術文件極重要的課題。後者是文字內容本身的可讀性和合理性，文件的目的是要傳達訊息給讀者，能讓人「看的懂」是重中之重的要務。

要讓人看的「懂」的要求可不是廢話，文筆通順沒有錯字只是文件最起碼的要求，如何才能讓讀者在最快的時間內讀懂一個觀念，或是學會如何操作一個軟體和機器，個中學問實在是不簡單。比如說是否以例子來帶動敘述，或是要不要用對話體例來說明新觀念、新事物；有些表達方式，和文字的特性有關，比如英文的時態（tense），主動和被動態（active/passive voice）等等。筆者的第一篇學術論文，在整理相關文獻（related works; literature reivew）時，引用了領域內開山祖師成名作裡面定義專有名詞的句子，被指導老師批評 ambiguous；有些人為了體現論文的權威性和客觀性，認為論文裡的敘述句都要用被動態，「我們觀察到一個現象」都要改成 It is observed that...。

還有，中文在處理主詞和第三人稱時，比英文要簡潔許多，而英文常見到的 ... of ... of ... of 的句子，若是要用中文表達，就得拆成幾個短句才行。語言的特性必然影響文件的撰寫方式，不同性質的文件，對於某些特性的「敏感度」又有所不同，「通順易曉」的要求說來簡單，執行起來難度不小。像白居易那樣，詩能寫的老嫗能解，實在是了不起啊！

最後，Jacob 提了You need an editor 的建議 - If you really want to produce great documentation, it needs to be edited！很多時候，我們不見得能那麼幸運的擁有專業編輯的協助，但是換個角度設身處地審閱文件，運用工具找出基本的文法和用字的錯誤，至少是撰稿人必須做到的；三人行必有我師，同事、同儕也能提供許多寶貴的建議，我想這樣至少能做到起碼的品質保障吧。

The Strategy to win Rock-Paper-Scissors！

I came across the introduction to strategy to win rock-paper-scissors the other day. The visualized map mentioned by Flowing Data is awesome.

昨日之日不可留

今天下午，終於決定回到業界公司任職，下個月初上任報到。新單位的總經理本為舊識，在他的辦公室裡面「氣氛良好」的聊了十分鐘後，我們爽快的達成共識，人資專員效率驚人，五分鐘後把熱騰騰的 offer letter 送進辦公室，兩人當場完成一式兩份文件的簽字手續。

距離通過博士論文口試（dissertation defence）將滿三個月，過去九十天，時而興奮時而惶惑，心神始終在不知所謂的狀態下，白天半睡半醒的在網際網路上閑逛，晚間邊啜着烈酒邊改寫十年來從沒更動過的簡歷和自傳。拿到證書那天，發現這個學年度，我有資格投寄簡歷的學術單位，竟然只有兩個。因為決定「衝關」的時間太晚，註定趕不上這個學年度的人事作業，雖然對於大環境的不利早有心裡準備，但要真正直面關閉的「大門」，心內怎能不惻然。

考慮個把月，和老朋友聊聊後，還是回到產業界，這回因為有「學位傍身」，新的定位是產品研發部門的主管。不再像以前需要那麼頻繁的「拋頭露面」或是要打理公司的 daily operation。但是我很明白，新的角色在半年到一年內，不太需要我過去五年在校園所學，主要仰賴的還是我的管理和協調的經驗；如果一切順利，我才能在  R&D 的這個 R 字上有所著墨。面對這樣的結果，除了點一首 C'est La Vie 給自己，還能說什麼呢？

新單位開發的產品有二，一是資料庫（數據庫）性能調校，第二個也是未來幾年的重點則是資料庫稽核（ Database Activity Monitoring , DAM），兩者和我熱愛的 cyber culture 、recommender 距離都有點遠。未來幾個星期，要努力的掃蕩各相關業者的白皮書和市場報告，網際網路的議題是要暫且放下一段時間了。 Data Mining 在 DAM 領域還是有些「文章」可做的，如果我能撐到把新單位的 R&D 兩個面向都做出點成績，那時或許可以整理點東西出來吧。

總覺得說什麼「告一段落」或是「展望未來」都是廢話，這時心裡翻來覆去的只有一句：昨日之日不可留....

情人節

憩

台北榮民總醫院生活廣場前有片小空地，空地裡有個小圓環，週遭種了幾棵樹，每天午後總有三五十隻麻雀在樹上和空地間穿梭，時而在圓環裡的空地閑庭信步，方步踱久了，就飛到樹枝和樹梢小憩。

追