[碎碎念] 程式開發領域由菜鳥到老鳥的成長歷程 (26) - 老鳥階段-寫文件的藝術。

老鳥階段指的是工作五年以上的資訊人,五年說短不短,相信除了程式設計功力已經升上高手之列外,也累積了不少心得和技術的概念吧 (例如物件導向),到了老鳥階段,除了要再繼續精進功力外,適當的把心得和成果對外分享,也算是做功德吧。

前一天才大概講講寫文章來訓練表達能力,今天就來聊聊一些寫文章上的兩三事。

寫文章可以由目的 (purpose) 來決定寫作的方式,這裡說的 "目的",是指文章是要給誰看的,筆者有寫過一般的部落格文章,投稿雜誌的文章,編成書的文章,當然也有給客戶看的規格文等等,這些文章雖然都是在講技術,但內容走向完全不同。

1. 部落格文章

部落格基本上是自己的天地,所以愛怎麼寫就怎麼寫,多半也沒人會管你,只是如果是要把部落格當成自己的門面之一的話,就不能隨便亂寫了,筆者看過很多部落格,文章都只有一兩行就交代過去,或是只貼個沒什麼整理的 code 就當一篇文了,部落格是公開的環境,只要搜尋引擎有去過,就一定會抓取其中的內容到索引庫,網友在搜尋時也都會搜的到,只是點進去看幾秒後就失望的離開了

這還不打緊,如果是共筆部落格或是自己的文章會被貼到公開領域的文章列表 (ex: 點部落,無名小站或是大陸的 CSDN 或博客園等),那問題可能會比較嚴重,因為所有的人都可以公開領域進入部落格的文章,一定也包含了一些該領域的先進專家,或是你的主管 (或未來的主管),當他們看到這種沒什麼 quality 的文章內容時,心理會怎麼想?

所以,除非是私領域的部落格,或是永不公開的部落格文章,怎麼寫都沒人會管,想在上面罵主管或是批評時事都無妨,但如果是會出現在公領域的,就要對自己寫的內容負責了。

(延伸閱讀:http://blog.csdn.net/oiio/article/details/6913156)

2. 投稿的文章。

想投稿給雜誌的文章,和寫部落格的技術文很相似,但多了兩道關卡,一個是字數,另一個是審查。

不管是哪一本雜誌,因為要廣納百川集結多數人的作品,在有限的篇幅下,一個人的稿件字數一定不能太長,以筆者投稿 RUN! PC 為例,字數通常會在 2500-3500 之間,如果超過的話,除非刊出當期稿量少,得以全部刊出外,編輯都會將文章切成兩個部份,視文章長度決定,愈長的文章切得愈多,有時也會刪除一些文字。當然編輯通常會和作者討論要刪除哪些文字,以免文章失真。

在投稿之前,作者要提交一份大綱給編輯,單篇文章的話可以直接附上全文,連載型長篇文就要提交大綱,說明系列文章的走向以及大概的內容,編輯會在收到文章時對內容進行核對 (技術編輯/責任編輯的工作),並且修改文章內容為雜誌的工作稿格式,最後才會交由美編排版成雜誌版後付梓,至於技術的內容則可能會受限於技術編輯的專業知識而較少被核對,最終的成敗都要由作者來負責,所以投稿文章是不能亂寫的,而雜誌的流傳速度也不會比網路慢太多,也因為是印出來的,會比部落格的技術文更能當作門面。

除了雜誌以外,還有更嚴謹的期刊,不過那是學術界才會有的,或是研討會的徵文,那些都是論文等級的文章,當然排版格式上也有一定的限制,內容也會有一定程度的要求 (審查的多半是教授),通常有唸研究所的都會有這一段的訓練,所以筆者就不在這介紹了。

3. 編輯成書的文章。

當文章量累積到一定程度,或是有很大量的心得想分享時,寫書也許是個不錯的選擇,只是寫書之前都要先找好出版社洽談,最好是有些原始稿件,這時部落格和雜誌稿就派上用場了,畢竟編輯決定作者可是要先做過審查的,有一些作品會對編輯審查有正面影響。當編輯決定好時,會和作者簽約以取得可重製以及獨家出版的權利,並約定稿費的計算方式,以電腦類技術書籍為例,合約期通常會是三年以上。

寫書和寫部落格就差很多了,部落格可以是零散的,心得分享的,不需系統化整理的文章,但是書籍就需要做系統化的整理,要排定章節以及要撰寫的內容 (即書籍大綱),又由於讀者群的不同,內容的難易度也要做一定程度的拿捏,內容也要是有整理過文章,通常要配合圖說以及程式碼,所以寫書要準備的資料會遠比部落格來的多,當然,若平時寫部落格文章時就有做這些事,那寫書當然也不是難事。

如果是集結文章成書的,即便是部落格已經有寫好的文章,但因為要整理以及將它系統化,不能就直接拿來貼,而是要再潤飾過,才可以編入書中,否則讀者會有讀起來卡卡的狀況,適當的安排圖以及 sample code 會讓讀者比較容易閱讀,這也要看書編寫的屬性如何,初學用書會需要更多的步驟 (step-by-step),而中高階則是強調概念

4. 給客戶看的文章。

既然是給客戶看的,當然不能造次了,客戶想看什麼就寫給他什麼,像是服務建議書 (Proposal),需求規格書 (SRS),系統分析書/設計書,測試報告,技術要點,範例,結案報告等等,不同的需求有不同的寫法,和寫書還蠻像的,但因為是要針對客戶的口味,所以讀者就只有客戶而已,只需對客戶想要的部份去做編撰即可,然後適時的加入一些創新的東西 (Proposal 這點很重要),不過也不要寫太多而變成承諾太多事,會讓案子可能收不了或做不完,這就麻煩大了。

以上是筆者個人寫過的文章類型,分享一些寫作上的技巧,但每個人都有自己獨特的行文風格,筆者只是大概的分享一下自己的作法而已,僅供參考用 :)