開源文檔的五個趨勢

開源文檔的五個趨勢

Shaun McCance

我在開源文檔這方面作過很長時間。在過去的二十年裏，關於創做和出版方面的見解改變過不少次。有些趨勢看起來是在兜圈子，好比說語義標記的流行。最近的趨勢則是文檔向代碼靠攏，即所謂的文檔如代碼。咱們來看看文檔趨勢的幾個大方向。

1. Git

當我最開始在GNOME作文檔工做的時候，咱們用DocBook寫文檔並與代碼一塊兒存在CVS裏。如今GNOME用Mallard寫文檔並用Git管理。雖然文檔格式和工具始終在變化，文檔一直如代碼同樣存放在版本管理系統中。

好久以前就作的事情稱之爲趨勢有點奇怪，可是在Git出現以後確實是有些東西改變了。Git大概是二十年前出來的分佈式版本管理系統。不少人並無掌握它，他們仍然沿襲CVS或SVN的方式來使用Git。文檔編寫者也在不斷熟悉Git，他們創建開發、臨時、產品等分支，合併不一樣人貢獻的文檔，這在幾年前並不尋常。

Git不是惟一的一個分佈式版本管理系統。還有Bazaar和Mercurial等，寫做者也能象Git同樣使用這些工具。可是由於有衆多流行的Git託管網站因此大多數人仍是在討論Git使用上的問題。

軟件文檔行業上是開源主導總體的趨勢。看一下技術寫做論壇，裏面都是各個行業的人們想要了解如何有效的過渡到Git上。過去他們多是將文檔直接存於公司網絡或者使用專有的系統來管理。Git及相似工具極大地改變了整個軟件行業處理文檔的方式。

2. 輕量語言

文檔編寫的格式有不少種選擇。有SGML而後是XML語法格式；有TeX和troff的各類變體；有字處理、版式工具和各類協助創做軟件的文件格式；有各類不一樣wiki和內容管理系統的內部格式；有HTML。還有一批的輕型標記語言被設計出來以便於在文本編輯器裏輸入。

人們逐漸選擇輕量級的標記語言有多種緣由。它們一般便於編寫簡單版式的東西，它們能更好的由版本控制系統管理，它們能下降新人加入的門檻——可是也不要期望單靠改變文檔格式就能讓不少人蔘與到你的項目中...

輕量標記語言也有本身的弱點，跟它們相關的工具使用範圍有限，而且一般不能提供其它工具所需的數據模型。它們也並不支持太多的語義信息。如XML則否則，有大量工具能夠用來作翻譯、校驗、連接檢查、狀態報告、各類類型的測試和數據提取。輕量格式中不多有這些工具，因此雖然輕量格式下降新人的准入門檻，它們也對資深人員樹立了新的問題。總要有所取捨。

如今最流行的三種簡便格式是Markdown，AsciiDoc和reStructured Text。
Markdown最簡單提供的功能也最少，基本知足大多數基本的文檔需求。Markdown有不少略有不一樣互不兼容的風格，看你使用什麼樣的處理工具。
AsciiDoc支持更多的語義和類型，它本來是做爲DocBook的前端，但如今已發展成爲獨立並支持多種輸出格式的語言。
reStructure Text源自Python社區，而且很長時間內只在Python項目內使用。它之因此流行起來是由於一些文檔託管網站，如Read the Docs。

3. 靜態網站生成

五年前的趨勢是用wiki和博客平臺來創建文檔站點，搭建容易也利於分享。有些人甚至開放本身的wiki給匿名用戶。如今則是在版本控制系統裏保存文檔，編譯和發佈幾乎都是靜態HTML文件的站點。

靜態站點由來已久。我大學畢業的第一份工做就是在一家軟件公司用內部工具編譯和發佈成百上千頁的文檔。但如今靜態站點逐漸在各類項目中流行起來有幾個緣由。

首先有不少現成好用的靜態站點生成工具。象Middleman和JekyLL，跟wiki/博客同樣配置簡單。除非有特別的要求，你基本上不用維護本身的生成工具。這些工具在網站開發者和技術做者中已蔚然成風。

另外一個緣由是愈來愈多的技術人員選擇使用代碼託管網站。wiki的一個好處是任何人不用安裝什麼東西就能夠編輯它。若是你的文件存放在GitHub上的話，其餘人就能直接瀏覽器裏編輯並給你提交合並請求。

4. 持續集成

持續集成是鏈接趨勢的重要部分。你能夠用簡單的格式寫文檔，放到Git裏而後經過Git託管服務在頁面上編輯，直接發佈它們。依靠持續集成甚至不須要人來啓動發佈過程。你能夠像使用wiki同樣在每一個提交後自動發佈。

有些項目比較謹慎，它們只在產品分支上發版。持續集成作了那些瑣碎重複的事情，你也能夠自動發佈開發分支的階段性文檔站點。

持續集成並不只僅意味着發版。項目能夠利用它來作文檔的校驗和連接檢查，給出狀態和覆蓋率報告等。

5. 文檔託管服務

雖然持續集成讓自動發佈文檔比以前容易不少，不過託管網站幾乎包辦了全部事情。告訴他們一個Git倉庫，他們會自動編譯、發佈、託管你的文檔。最著名的例子是起源於Python社區的Read the Doc，它的易用性適合各類類型的項目。

免費文檔託管網站如何盈利還有待觀察，運營這樣的網站人力和費用上花費不菲。若是這些網站無覺得繼，咱們就只能另尋他處。我鼓勵每一個人都能在資金上爲它們盡一份力。

我相信託管服務會走下去，人們總能找到問題的解決方法。我也看到託管服務對非開源軟件開始收費。開源在過去二十年裏引領了文檔技術的道路，也將繼續如此。