程式設計者的技術文筆與寫作

程式設計者是工程師？科學家？工匠或藝術家？Robert C. Martin在《Clean Code》書中第一章即談到：「We Are Authors」。Bruce Eckel在2009年於Artima Weblogs寫了一篇文章〈Writing Software is Like ... Writing〉。《Coders at Work》書中，多位大師也曾提及文筆表達能力對程式設計者的重要性。

作家使用自然語言撰寫著作，程式設計者使用程式語言撰寫程式，兩者都是使用書寫能力，將心中的想法具體為實際的文字，身為程式設計者應具有一定程度的技術文筆，因此，偉大的程式設計者往往也是卓越的技術作家。

文筆代表溝通與組織能力
寫作的出發點是溝通，可培養有條理的述事能力。寫作時總會有一或多個預設的讀者，基於對這些預設讀者解釋你所理解或想表達的事物為何，必須有一個條理順序來進行說明，在這個過程中要考慮到如何引導、如何漸入、如何深入、如何應用、如何淺出、如何結論，這都是訓練個人思路的一種方式，也是分析事理或問題的基礎。

程式設計的出發點也是溝通，程式雖然由電腦解讀執行，然而實際溝通對象是人而非冰冷的機器，程式設計者本身是作者，也會是另一程式設計者的讀者，在撰寫程式的過程中，閱讀程式碼佔了重要的時間比例，你總得先瞭解已撰寫的程式碼，才能瞭解程式碼的目的，目前程式碼情境的閱讀難易度，決定了接下來撰寫程式碼的難易度。

在程式討論區或郵件往來中，你經常可以發現，有些提問者無法清楚地陳述問題或想法，雜亂無章的說明透露出「此人連問題都無法清楚表達，更遑論寫出來的程式碼」，檢視隨著問題附上的程式碼，通常如所預期地雜亂無章，令閱讀者無心或無力解決其問題。很多時候，閱讀糟糕的文件與閱讀糟糕的程式碼沒有兩樣，文筆過差的程式設計者，在程式撰寫上通常也不會有清楚的邏輯。

許多人沒有思索過如何以流暢文字表達問題，通常也代表著本身沒有努力去理解過問題本身，也就無力辨識潛藏在理解問題過程中的解答。

嘗試明確或有條理地以文字陳述問題的過程，就是在嘗試組織出解決方案的過程，答案或想法往往因此而浮現。《Coders at Work》作者Peter Seibel就曾舉例提到，某電腦科學系中必須對毛絨玩具先陳述問題始末，方可進一步向教授請益，而往往在與大熊先生解釋問題的過程中，答案就因應而生； Erlang程式語言之父Joe Armstrong也提及，他經常在與同事說明問題情境的過程中就想到解答，而同事還搖著頭說：「我還不知道他要問什麼呢？」

雖然這些是以說話陳述問題的例子，然而組織出有邏輯的內容，以說明心中思維的概念，其實相同。口述或許還涉及思考速度及臨場反應問題，然而寫作可以有足夠時間組織腦袋中的訊息，透過文字條理地寫下說明，如果程式設計者用自然語言都無法條理分明地進行陳述，又怎能期待他可以用程式語言來清楚地架構解答？

技術寫作能訓練重構與抽象能力

在程式設計上，重構代表了對既有程式作架構組織上的調整，以求程式符合進一步的需求變化。

在技術寫作上也經常發生重構，這往往發生在一開始陳述問題的起點不對、說明過程的順序不洽當，或者修飾若干詞語來改善整體文字的緊湊、抽象與深度。

在寫作的過程當中，必須時時站在讀者的角度來審視自己的文件，確認身為讀者的自己滿意且可清楚地從文章中看到想表達的觀點，往往在檢視的過程中，可發現重複、多餘字眼、過於薄弱的語句或段落，過於冗長的陳述或區塊。這與重構過程中進行程式碼檢視，以發掘重複程式碼、多餘語句、職責過大或過小物件、程式碼過長方法的過程類似。

抽象化的思考，是程式設計中獲得彈性時必要的能力，技術文件撰寫有時也需要抽象化思考能力。有時想陳述的對象、模型或觀念，具有某些共同或相近特質，個別逐一描述並非適當方式，此時得以更高層次的思考與表達方式來描繪這些特質，這迫使你進一步思考這些共同或相近特質的深度與意涵，像是在陳述類別基礎的語言特性時，並非著墨多個類別語言在語法層面的差異性，而是以典範（Paradiam）甚至管理層面來思考這類特性存在的意義為何。

抽象概念有時覺得自己沒辦法清楚表達，或用簡單的方式加以比擬，多半是因為沒有透析它的本質，正如愛因斯坦所言：「If you can't explain it simply, you don't understand it well enough.」技術寫作可以測試對技術或設計的瞭解程度。

技術寫作時該秉持著一個態度：「知之為知之，不知為不知！」為文過程中對觀念或設計無法說明清楚時，有可能是對它的瞭解程度不夠，甚而有些不知所云的感覺。

以大量閱讀淬煉想法與文筆
將想法表達成文字終究存在差距，無論是程式設計或是技術寫作，過程要能流暢，總會需要足夠資訊，大量閱讀是必要的過程。

有些人剛開始嘗試技術寫作時，往往寫幾個段落就不知如何進行下去，因而覺得技術寫作有困難，這大多是由於資訊收集不夠，無法累積想法；在收集的過程中，會對技術本身有更多認識與靈光一現，更能深層思考相關議題，也從而得到更多的資訊管道，大量閱讀成果將不僅呈現在文筆之中，更會呈現在程式碼的寫作之中。

優秀作家會透過大量閱讀，瞭解其他優秀作家的寫作角度、風格與內容，從中習得各種觀點與文筆技巧，程式設計本身也講究大量閱讀，唯有透過大量閱讀優秀的程式碼與文件，才能習得各種設計觀念與實作技巧，提昇撰寫程式的流暢性與彈性。

在大量閱讀的過程中，總會激發許多零星的想法，這些想法經常是模糊且破碎，若僅是將這些想法單純地記錄於文件中，很容易看出零星想法彼此間的不協調而難以成文，閱讀與理解之間畢竟存在差距，透過技術寫作來組織與表達是彌補這個差距的方式，零星、模糊且破碎的想法，在這個過程中有些會被吸納，有些則會剔除，因而得以過濾不必要的雜訊，掌握中心的想法。

以技術寫作記錄假設與論證

正如同《Shark Tale》（編按：鯊魚黑幫）主角Oscar最常出現的開場白：「You might think you know me, but you have no idea!」，此話雖然出現在卡通中但含意深遠。

有時閱讀是一種體會，真正去動手作時，才發現根本不是你想的那回事。有時候文件中表達的內容，是作者基於長久經驗歸納而得的結論，沒有實際經驗的讀者單看文字容易產生誤解，雖然作者透過文字傳達自身經驗，但存在於文件的內容只能稱為知識，唯有親自動手才能成為你的經驗。

無論是理論性的論證與計算，或是技術性的範例應用，寫作對於使用的技術提供試誤機會。

在技術寫作過程中，不免要以玩具式的實作來印證自我假設是否正確，過程中，往往會發覺忽略掉的細節或誤解。在允許的情況下，將撰寫的文件分享出來，給予他人對你進行驗證，有時以為已理解的東西，在別人看來並不透徹，分享讓別人有機會驗證你的想法，從而修正謬誤，這間接理解及改正錯誤的能力，藉由他人的互動與回應，可以得到更多的資訊與想法，拋磚引玉正是這樣的道理。

技術寫作可以建立個人的資料庫，他人的著作或文件，總是無法為自己量身訂作，而該記錄些什麼，除了自己知道之外別無他人，日後有所遺忘，循著既有的文件記錄，可更快取得昔日記憶的軌跡，甚至比對兩個不同時空間下自身思慮的不同。