技術寫作產能工具

現今已有不少文章談及寫作對身為開發者的好處，如果開發者打算開始或已從事技術寫作有一段時間，就會遇到一些大大小小影響寫作產能的問題，甚至遇到寫作平臺關門大吉，不得已要搬家的痛苦。若能使用一些相關的產能增進工具，來解決這些問題，就不致徒然耗費心力在這些與寫作本身不相干的問題上。

改用Markdown吧！

早期我使用HTML來撰寫技術文件，原因在最初直覺地認為，寫完的東西就是要放在Web上，當然就使用HTML，現今有些寫作平臺，預設也是提供所視即所得的HTML編輯器，對於不瞭解Web技術，純粹只想在Web發表想法的人來說，HTML算是還行得通，不過對開發者不見得是個好方案。

如果開發者不得不去處理HTML原始碼本身，就會發現HTML太寬鬆、太自由、標記太囉嗦，因為，原始碼當中有許多資訊是給瀏覽器看，而不是給人閱讀，這就跟HTML中夾雜程式碼的問題類似。

HTML中若夾雜文件主體，想在HTML標籤中調整文件內容，就會痛苦異常，如果使用的所視即所得HTML編輯器會自行加入額外資訊，就會使得HTML原始碼內容更加雜亂了。

實際上對開發者來說，技術寫作時使用的格式越簡單越好，這樣用任何一種編輯器來打開，才能馬上識別文件內容，以我為例，無論是寫技術、專欄或翻譯，現在多半習慣使用空白的文字檔案來起草，在需要標記文件中特定內容時，像是標題、程式碼、列點時，則使用Markdown語法，原因如我在先前專欄〈手不離鍵盤的輕量標記語言〉中談過的：「Markdown的標註都是由標點符號所組成，這些符號不會太難，也不會過於干擾閱讀」。

任何文字編輯器，都可以編寫Markdown語法是最大好處，如果開發者的文件最後想在Web呈現，而在寫作過程中，想要預覽網頁呈現效果，可以選擇可關閉、展開的兩欄式編輯器，以自由選擇是否在編輯時對照所視即所得的畫面，有些編輯器（像是MarkdownPad Pro或線上的StackEdit）可設定套用的HTML樣版與CSS樣式，開發者仍可專心寫作，至於HTML甚至PDF轉換，只需交給程式處理。

唯一要注意的是，原始的Markdown基本語法不多，因此，有不少編輯平臺或工具對Markdown語法進行擴充，像是支援GitHub風格的GitHub-flavored Markdown，或是支援公式、圖表的R Markdown等，如果將來想將Markdown文件轉換為電子書，則要注意電子書轉換程式要求，盡量用基本Markdown語法，必要時再用擴充語法，可減少麻煩。

不斷熟悉Regex來處理文字

我在先前專欄〈Regex的強大與哀愁〉談過Regex，儘管學習與熟悉Regex的使用需要不少時間，不過對開發者來說，絕對是報酬率極佳的長線投資，除了在開發上可用來分析Log、設定檔等之外，Regex用來處理技術文件也是很方便的工具，如果技術文件一開始使用的就是Markdown，處理起來就更為輕鬆。

舉例來說，日前在翻譯書籍時，雖然出版社要求譯文使用純文字，不過當中卻規範特定文字的標記得使用<b></b>、<code></code>等，每次進行這些標記總會中斷翻譯的思路，在這樣過了幾個章節之後，我就直接改用Markdown標記了，最後的譯文只需透過Regex轉換為HTML標記，就可以符合出版社格式要求。

回過頭來看，使用Regex處理HTML文件不是個明智之舉，因為HTML並非Regex能妥善處理的語法（HTML是Context-free語法，Markdown不是），HTML文件中往往會出現Regex難以描述的規則，網路上有許多人建議別用Regex來剖析HTML（儘管有人主張可以將剖析任務分解為各個子任務，但麻煩又要額外撰寫程式），最近我想剖析網站上諸多HTML文件，將內容抽取出來以套用至新風格時，也徹底體會到使用Regex來處理HTML的痛。

熟悉Regex在文字處理上帶來的產能效益，無庸置疑，但不必試圖在朝夕之內熟悉Regex，先選用一個可以支援Regex搜尋、取代的編輯器來編寫文件（Windows使用者，至少換個NotePad++），有助於多熟悉Regex，有些編輯器（像是vim）還可以在使用Regex的同時，附加小程式，這就可以在不另外撰寫程式的情況下，完成特定的文字處理任務，除了編輯器之外，也可以針對不同的需求，採用一些支援Regex的工具，像是grep、sed、awk等。

只要經常運用這些可套用Regex的工具，就會發現Regex的熟悉其實是個漸進式的過程，並不是看過幾個Regex符號、量詞等之後，馬上就要能編寫出適當的Regex來處理文字，而是在可支援Regex的工具中，先從簡單的Regex開始，運用的越多，就更能瞭解文件中的「文字規則」。

這很重要，處理文字時常面對的問題，並非不懂Regex語法，而是不瞭解文字規則，編寫不出合適的Regex，或者是察覺不到可運用Regex的場合，多使用Regex，就能多瞭解文字規則，從而更瞭解Regex語法，接著會更常用Regex，這是持續迭代的過程。

使用基於Git的工具

對許多開發者來說，Git版本控制系統已經不是陌生的東西，除了可應用在原始碼的控管，撰寫技術文件時，實際上也得考慮文件更新與版本控制、多人協作等問題，無怪乎現在許多人選擇將文件放在GitHub這類平臺，就連美國白宮也將政策草案、年度預算等放到了GitHub；文件若想要有效運用Git，最好是使用純文字編寫，因此Markdown檔案自然是首選之一，Markdown也是GitHub預設支援的格式，使用瀏覽器觀看Markdown編寫的md檔案，也會自動將Markdown語法轉為HTML以供瀏覽器顯示。

但GitHub畢竟不是專門為了技術寫作而建立的平臺，因而出現了一些基於Git的寫作工具，StackEdit是功能蠻齊全的工具之一，它除了提供所視即所得的Markdown編輯器之外，文件也可以儲存在Dropbox、Google Drive，或者選擇將文件發布至GitHub，便於開發者善用GitHub的版本控制等功能。

另一個近來能見度很高的平臺是GitBook，它基於Git建立，並且直接考量技術文件編寫上的各種需求，像是所視即所得的Markdown編輯器、也可以自動地將Markdown轉換為PDF、ePub、mobi等電子書格式，甚至包辦了出版及販售電子書的相關平臺功能，越來越多開發者選擇在GitBook撰寫技術文件，甚至其他領域的使用者也聞風而來，就連現任臺北市長之前在競選時，也運用GitBook來發表市政白皮書。

相對於Leanpub這類更針對一般寫作者，以編寫、發表與販售電子書為主的平臺，使用可基於Git的GitHub、StackEdit或GitBook，雖然要多瞭解一些技術細節，卻可以得到較多彈性，例如GitBook上每份技術文件，實際上都有個Git網址，只要開發者會用Git指令，在安排文件相關資源（例如圖片、範例原始碼等）時可以更有彈性，也可以讓讀者直接對文件做出貢獻，像是發布Pull Request給文件作者。

這十幾年來，我的網站因為採用HTML文件累積了不少債務，過去想到要整頓這些文件，就直接打退堂鼓了，後來有次想將整本書轉為HTML時，想到可以試試Markdown，不久又在將之轉換為ePub格式時借用了Regex來做前置處理，而這本書的Markdown在遷移至GitBook時亦相當快速。

在接連嘗過甜頭之後，後續文件因而都遵循此模式，而這些新文件最近在轉換為新的網站風格很順利，才終於想一鼓作氣更新整個網站，一次解決所有債務，過程中，我也逐一體會到過去不重視文件格式、編碼、結構不統一等帶來的成本。

當然，如果一開始就能熟悉這類產能工具，就能減少後續文件在維護時付出這些不必要的成本，雖然一開始學習、熟悉與採用這些工具，會造成短期內產能的降低，不過，後續產能效益相當驚人！