手不離鍵盤的輕量標記語言

專業的程式開發者，撰寫程式時會留意未來可讀性，透過適當編輯工具與程式樣版定義，可讓開發者無需分心於程式碼結構與風格，專注於程式內容的撰寫。

優秀開發者亦會從事技術寫作，良好技術文件就如同良好程式碼，若能認識並透過適當工具輔助，開發者就能專注於技術寫作內容，而非紛擾於文件的結構、樣式、雜亂的格式，甚至是文件版本。

專業的技術寫作者，對於其撰寫內容如何呈現也必然有所要求，著名技術作家侯捷便十分重視文字呈現，為了避免他的書中任何一個字一張圖的大小型式顏色粗細位置……不在他的完全掌控之下，他決定親自排版，甚至因此出版了《Word 排版藝術》來分享其排版經驗，他在自序中談到：「文字欲以悅目的形象出現，就需要良好的編排。」

我在從事書籍寫作或翻譯時是使用Word，也研讀過《Word 排版藝術》，不過幸運地，我遇過的編輯認真負責，排版者也有相當高的專業，因而我無需全盤操控編排的每個細節，使用Word之目的，單純是想大致呈現排版外觀，我會事先擬訂好章、節、列點、標號、圖示、程式碼等結構，接著就專注於內容編寫，排版者在我的基本排版外觀下，考量印刷效果並進行樣式套用，後續再透過數次校稿過程，確定實體書籍具有良好編排。

如果是編寫網站上可閱覽的系列文件，我選擇使用HTML文件，HTML有定義結構用的標籤，可使用純文字編寫，可透過樣式表來決定編排樣式，似乎是最佳的選擇；不過標籤與樣式，顯然較適合給機器讀取而不是給人閱讀，因而我會有個樣版網頁，事先定義好文件的結構與樣式表，每篇新文章都使用樣版網頁，搭配所視即所得HTML編輯器（早期使用Nvu、KompoZer，現在使用BlueGriffon），以求能專注於內容的撰寫。

寫作iThome專欄我有些自我要求，內容不能只是教學文件，不能只是「掉書袋」純談沒接觸過或親身體驗過的東西，偏好結合近日從事活動中看到、聽到且有深刻想法之論述，因而在各種寫作主題中，寫作iThome專欄最具有挑戰性，為了徹底專注於內容，我使用的工具是純文字編輯器NotePad++，通常事先只擬定四個子標題，每個子標題前放個「-」符號作為識別，這可避免我分心思考額外的綱要層次，也避免了各種樣式操作上的紛擾。

使用輕量標記語言

在各種寫作格式與工具中，我選擇使用純文字與簡單的標記，以免被結構與樣式給分心，即便是使用HTML或Word，我也是事先定義好結構與樣式，以便讓自己可專注於寫作內容。

使用純文字與簡單標記令自己專注，其實多數人都有類似經驗，只不過這種自定義的簡單標記沒有互通性，自用可以，要與人交流就得事先溝通標記的意義，為了有一致標準，出現了各種標記語言。

標記語言是用來擴充文字的語義，HTML當然也是標記語言，使用<h1></h1>到<h6></h6>之類來表示標題、<p></p>來表示段落等，語義上似乎是蠻清楚的，只不過標籤外觀上實在是太突兀，如果結構表現稍微複雜時，想從結構上分辨與閱讀內容時就會發生障礙，最終你不得不搭配所視即所得編輯器；類似情況，也發生在其他語義豐富、功能強大的標記語言，像是LaTex，這類標記語言最後適合當作給工具呈現外觀用的中間格式，而不是給人直接閱讀的格式。

如果需要複雜的編排效果，功能強大的標記語言確實有必要，然而從事技術寫作，通常不需要過於複雜的編排效果，因而有些標記語言以輕量級（Lightweight）取勝，成了技術寫作者的選擇。輕量級標記語言的定義是非正式的，可使用純文字編寫是基本要求，標記本身必須易學易用，最好容易到看個五分鐘就可以著手撰寫內容，標記符號本身不能太突兀或複雜，即使不透過所視即所得之類的工具，也可以輕易從原始純文字中進行內容閱讀。

以目前來說，最受鎂光燈關注的輕量標記語言是Markdown，雖然原因最主要還是來自GitHub對Markdown的支援，像是可在評論或.md檔中使用Markdown語法，幾乎算是GitHub的官方標記語言。Markdown目標是「易讀易寫」，語法最大靈感來源就是純文字的電子郵件格式，想想你會在純文字的電子郵件中如何標註，就會知道為何Markdown的標註都是由標點符號所組成，這些符號不難，也不會過於干擾閱讀，就如同你不會在純文字電子郵件中，搞些很難撰寫或障礙閱讀的符號。

考量DRY、多人協作與版本控制

易讀易寫、可專注內容，是技術寫作時採用的工具與文件格式考量，就開發者來說，最好還能兼顧DRY與版本控制。開發者對於DRY應該都很熟悉，就是不重複（Don't Repeat Yourself），在技術寫作上不重複的考量之一就是少碰滑鼠，滑鼠點選操作其實充滿了大量重複動作，手離開鍵盤也會從寫作的情境中分心，因此輕量級標記語言偶而還有個更令人會心一笑的需求：撰寫時手不能離開鍵盤。

不重複的考量，還包括了可以輸出為其他格式，像是HTML、PDF、EPub等，這點在今日閱讀平臺多樣化的世界尤其重要，你應該不會想要為了不同平臺，重複花費心力與時間在編排格式上。有些標記語言易於從文字轉為HTML，Markdown也受到這類語言的影響，因而在Markdown中對HTML是很親切的，你甚至可以在Markdown文件中直接撰寫HTML（不過不鼓勵）。

在《The Productive Programmer》書中，提到了〈DRY Documentation〉，因為要求開發者將註解文字再記錄至Wiki而惹惱了他們，因而撰寫了個小工具，自動從提交的程式碼中抽取註解文字發布至Wiki；實際上，不少語言都有這類工具，像是Java的javadoc、Ruby的RDoc、Python的reStructuredText等，在這類工具中，reStructuredText語義豐富（比Markdown多了一些）、容易閱讀、編寫，亦有不少人採用，Python從2.6之後，預設的docstring標記語言，就由LaTeX變成了reStructuredText。

《The Productive Programmer》中，也談到：「過時的說明文件比什麼都沒有還糟糕，因為那是積極在誤導」，這說明了開發者撰寫技術文件時，也得考慮更新與版本問題，多人協作可維持文件時效性，像是Wiki系統中也使用標記語言，也兼具了多人協作與版本控制的功能，由於輕量級標記語言可使用純文字，這就易於結合版本控制系統，而GitHub對Markdown的支援，只是明確實現這樣的概念。

專注而有效率地技術寫作
要能有良好寫作過程的基本前題，其實就是要能夠專注，我有不少一邊寫作一邊排版的糟糕經驗，因而無論是撰寫實體書、網路文件或者是專欄，我做的事前準備動作，其實就是為了減少寫作過程的編排操作，以便專心於內容的釀成；除了純綷寫作的難題之外，技術領域的寫作也會有其特有難題，這邊關心的是最初步、有關產能與效率的難題，像是不重複、多人協作與版本控制的考量。

輕量級語言表面上，似乎只是現階段捕捉到鎂光燈（幾乎就是在說Markdown），實際上，反映了純綷寫作及技術寫作時可能要面對與解決的一些難題，其實還有更多，像是數學領域，也許還會有公式圖表等更多標記考量（也可能因此不再輕量級），無論如何，應該採用最能專注而有效率的方案，用投影片寫規格書不會是聰明的行為，某個目錄中有xxx-v1.doc、xxx-v2.doc...，這表示你需要考量版本控制的功能，如果你不確定或懶得想，用個輕量級語言會讓你看來專業一點，幸運的話，還能剛好解決你的問題。