作為軟體開發人員,山姆鍋跟大多數人一樣不太喜歡寫文件,但文件 (尤其是 API 等技術文件) 其實就跟原始碼一樣需要即時的更新與維護。「影化身科技」的網站已經採用 Markdown 這種輕量級文件格式且所有內容都跟程式碼一樣進行版本控制,對於技術文件,自然希望採取相同的流程。本文說明山姆鍋選擇 AsciiDoc 作為文件格式的主要原因。

問題

在軟體開發過程中,不管是專案內部使用的需求規格、架構設計、還是外部使用手冊,或多或少都需要產出一些相關文件。文件的撰寫工具往往會限制文件生產的流程,而軟體開發文件因為常常需要配合目前軟體版本的變動,需要即時的更新來保持它的利用價值。

需求

作為軟體相關文件,底下是山姆鍋評估的重點:

1. 可以多人共同協作

文件格式或工具必須可以讓多人同時撰寫,使用電子郵件把文件寄來寄去這種方式不算是可行的作法。多人協作需要可以方便知道「誰」、「何時」、「做了哪些修改」,因此也就引申出版本控制的需求。

2. 支援版本控制

文件格式要能夠進行版本控制,除了可以支援多人共同協作,還可以利用持續整合工具來持續發佈最新版本以供除錯或審閱。

3. 支援多種輸出格式

文件就跟軟體一樣,要送達到最終的使用者手中才有價值。而為了達到這個目的,文件必須能夠以多種格式存在來讓使用者以最方便的方式讀取。

現有做法

底下是幾種常用來作為文件撰寫的工具:

1. 使用文書處理軟體

像是 MS Word、OO Writer 這類的文書處理器軟體,是撰寫文件的自然選擇。但使用文書處理軟體有幾個缺點:

  • 大部份使用私有格式,導致支援的編寫工具不足。
  • 難以進行自動轉換來輸出多種格式。
  • 「所見即所得」的編輯方式會讓寫手分心處理樣式而不是更重要的內容。
  • 不方便進行版本控制,無法有效協作撰寫。

2. 使用 Wiki 編輯軟體

過去山姆鍋也使用過像是 Confluence 這種 Wiki 軟體來作為文件撰寫工具,由於使用簡單的文字格式,編寫上相對簡單,藉由插件也可以支援多種格式的輸出。但使用 Wiki 軟體主要的缺點有:

  • 很難讓文件與軟體一起進行發佈。
  • 難以進行自動轉換來輸出多種格式。

3. 使用 DocBook 工具

使用 < a href="http://www.docbook.org/" target="_blank" rel="noopener">DocBook 作為文件原始格式並配合相關工具,可以說符合大部份需要。 DocBook 是一種 XML 文件格式規範,適合用來作為書籍、文件的撰寫格式,透過 XSL 樣式可以轉換成 HTML, PDF 等多種格式。由於是文字檔案,進行版本控制也是輕而易舉。雖然符合需要,但最大缺點就是 XML 語法過於繁瑣。

方案

在尋找比 DocBook 更簡單的方案的過程中,山姆鍋發現了 < a href="http://www.methods.co.nz/asciidoc/" target="_blank" rel="noopener">AsciiDoc 這個輕量級文件格式。它的目的基本上就是作為 DocBook 的簡易替代格式,使用流程上跟 DocBook 一樣。事實上,AsciiDoc 可以轉換成 DocBook 格式,因此可以運用 DocBook 現有工具。

AsciiDoc 是一種文字格式,採用與 Wiki 編寫類似的語法。對大部份的需求,AsciiDoc 都採用比 DocBook 簡單的語法來達成,對於 AsciiDoc 沒有支援的 DocBook 特性,也可以透過 AsciiDoc 的 Passthrough 機制來達成。Passthrough 機制簡單地說是讓您可以將 DocBook 的片段直接寫在 AsciiDoc 文件中,而這些片段會出現在最終產出的 DocBook 文件。

小結

從精實生產 (lean production) 的觀點,要盡可能將生產過程中的一切步驟自動化,作為開發流程的一環,文件的產出自然也不能例外。使用 AsciiDoc 這種文字型的文件格式讓文件就跟原始程式碼一樣,可以經過後製來得到最終格式化後的產物,從而讓開發者 / 撰寫者可以專注在產出內容上。