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

改用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時亦相當快速。

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

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

作者簡介


Advertisement

更多 iThome相關內容