【51CTO.com快譯】我個(gè)人有著多年開源文檔相關(guān)經(jīng)驗(yàn)，而過去十年中此類創(chuàng)作與出版的方式發(fā)生了巨大變革。其中某些趨勢(shì)似乎是種循環(huán)，例如評(píng)議標(biāo)記的再度流行。而有些則屬于新興趨勢(shì)，例如盡可能拉近文檔與代碼間的距離，很多人將其稱為文檔即代碼。下面，我將總結(jié)這一領(lǐng)域中出現(xiàn)的五種發(fā)展趨勢(shì)。

[[179287]]

1. Git

在最初開始參與GNOME項(xiàng)目的文檔相關(guān)工作時(shí)，我們使用DocBook進(jìn)行文檔編寫并將其同代碼一道存儲(chǔ)在CVS庫(kù)內(nèi)。如今，大多數(shù)GNOME文檔開始由Mallard編寫并存儲(chǔ)在Git庫(kù)中。盡管格式與工具有所變化，但將內(nèi)容存儲(chǔ)在版本控制方案內(nèi)的作法仍然延續(xù)了下來。

有些朋友可能會(huì)奇怪，為什么這種長(zhǎng)久以來的習(xí)慣仍然會(huì)被視為趨勢(shì)？這主要是因?yàn)镚it的出現(xiàn)。Git是一套分布式版本控制系統(tǒng)，大約誕生于十年前。當(dāng)然，目前仍有人在使用分散式版本控制系統(tǒng)，但Git的主流地位仍然不可動(dòng)搖。正是由于Git的普及，開發(fā)、分段與分支型生產(chǎn)方式為大多數(shù)人所接受，而這也是近年來值得關(guān)注的重要趨勢(shì)。

Git當(dāng)然不是惟一的分布式版本控制系統(tǒng)選項(xiàng)，我們也有其它方案可以嘗試。不過Git仍然占據(jù)著大部分比重，這很大程度上利益于Git托管站點(diǎn)的流行。

這一趨勢(shì)已經(jīng)引導(dǎo)了整個(gè)軟件文檔領(lǐng)域的潮流。過去，人們無(wú)法通過網(wǎng)絡(luò)驅(qū)動(dòng)器存儲(chǔ)自己的資源或者被迫使用專有型管理系統(tǒng)，但現(xiàn)在Git已經(jīng)徹底改變了整個(gè)軟件行業(yè)的文檔處理方式——而且這是一種可喜的改變。

2. 輕量化語(yǔ)言

在文檔源格式方面，我們總是擁有多種選項(xiàng)。語(yǔ)義XML格式、SGML格式、TeX方言以及troff方言等等。另外，還有面向文字處理、頁(yè)面布局以及協(xié)助創(chuàng)造的其它源格式選項(xiàng)。一部分輕量化標(biāo)記語(yǔ)言在設(shè)計(jì)中甚至專門進(jìn)行了簡(jiǎn)化，旨在優(yōu)化文本編輯器中的輸入方式。

輕量化標(biāo)記語(yǔ)言的興起有著多種原因。其通常更易于編寫，而簡(jiǎn)單正是每個(gè)人都樂于看到的效果。由于大多數(shù)輕量化語(yǔ)言面向行，因此其能夠在版本控制系統(tǒng)中良好起效。其也能夠有效降低新晉貢獻(xiàn)者的入門門檻，當(dāng)然大家應(yīng)當(dāng)謹(jǐn)慎變更源格式，否則很多貢獻(xiàn)者可能因?yàn)闊o(wú)法適應(yīng)而退出。

輕量化標(biāo)記語(yǔ)言也有著自己的短板。能夠與之協(xié)作的工具往往比較有限，且其通常無(wú)法提供編寫其它工具所需要的數(shù)據(jù)模型。其亦往往無(wú)法提供充足的語(yǔ)義信息。以XML格式為例，其中包含大量用于翻譯、驗(yàn)證、鏈接檢查、狀態(tài)報(bào)告以及測(cè)試與數(shù)據(jù)提取的工具，而這些工具目前在輕量化格式中并不普及。因此盡管輕量化格式能夠降低新晉貢獻(xiàn)者的上手難度，但總體來講仍然算是有得有失。

目前人氣最高的三種輕量化格式分別為Markdown、AsciiDoc以及reStructured Text。Markdown最為簡(jiǎn)單，但其能夠提供絕大多數(shù)基礎(chǔ)文檔功能。另外，其還提供多種尚有兼容問題的選項(xiàng)，具體取決于您實(shí)際使用的處理工具。AsciiDoc擁有更多語(yǔ)義以及更多元素類型。其最初專注于打造DocBook的前端版本，但如今已經(jīng)開始原生發(fā)展并支持多種輸出格式。reStructuredText來自Python社區(qū)，其發(fā)展速度極快并在不少托管站點(diǎn)中得到采用。

3. 靜態(tài)網(wǎng)站生成工具

五年之前，當(dāng)時(shí)的趨勢(shì)是利用維基與博客平臺(tái)創(chuàng)建文檔站點(diǎn)。這類站點(diǎn)易于設(shè)置，并允許人們更為輕松地進(jìn)行貢獻(xiàn)。一部分用戶甚至建立起自己的維基以進(jìn)行匿名貢獻(xiàn)。然而如今，趨勢(shì)轉(zhuǎn)為利用版本控制系統(tǒng)保存源代碼，而后通過大量靜態(tài)HTML文件實(shí)現(xiàn)站點(diǎn)的構(gòu)建與發(fā)布。

生成靜態(tài)站點(diǎn)并非什么新鮮事物。我的第一份工作就是為某家軟件公司開發(fā)內(nèi)部工具，用以構(gòu)建并發(fā)布包含無(wú)數(shù)頁(yè)文檔內(nèi)容的靜態(tài)文件。不過目前靜態(tài)站點(diǎn)已經(jīng)在各類規(guī)模的項(xiàng)目當(dāng)中得到普遍采用，而具體原因分為以下幾點(diǎn)。

首先，現(xiàn)成的靜態(tài)站點(diǎn)生成工具越來越多。Middleman與Jekyll都能夠輕松實(shí)現(xiàn)維基或者博客的部署工作。除非大家有特殊需求，否則直接使用現(xiàn)成工具即可達(dá)成目標(biāo)。

另一個(gè)原因在于，以靜態(tài)站點(diǎn)實(shí)現(xiàn)的源托管站點(diǎn)易于使用，且正有越來越多技術(shù)人員選擇這類方案。如果大家將全部源文件存儲(chǔ)在單一托管服務(wù)中，例如GitHub，那么任何擁有GitHub賬戶的用戶都可以通過網(wǎng)絡(luò)瀏覽器進(jìn)行編輯并提交其作出的修改。

4. 持續(xù)集成

持續(xù)集成已經(jīng)成為將以上趨勢(shì)進(jìn)行維系的關(guān)鍵。大家可以利用簡(jiǎn)單格式編寫自己的文檔，將其存儲(chǔ)在Git中并通過Git托管服務(wù)進(jìn)行在線編輯，而后發(fā)布至站點(diǎn)當(dāng)中。利用持續(xù)集成機(jī)制，大家甚至不需要人工進(jìn)行發(fā)布處理。如果愿意，大家甚至能夠自動(dòng)向master提交變更內(nèi)容，并借此實(shí)現(xiàn)類似于維基的管理方式。

某些項(xiàng)目則比較保守，即只允許由生產(chǎn)部門進(jìn)行發(fā)布。但即使是這種以branch為源頭的發(fā)布方式，持續(xù)集成仍然能夠顯著減少人為干預(yù)的必要性。大家也可以自動(dòng)發(fā)布分段站點(diǎn)以實(shí)現(xiàn)分支開發(fā)。

當(dāng)然，持續(xù)集成的作用絕不僅限于發(fā)布。各類項(xiàng)目皆可利用其自動(dòng)進(jìn)行文檔測(cè)試，或者根據(jù)狀態(tài)及覆蓋范圍生成報(bào)告。

5. 托管文檔服務(wù)

雖然利用持續(xù)集成實(shí)現(xiàn)文檔自動(dòng)發(fā)布已經(jīng)相當(dāng)便利，但如今的眾多托管服務(wù)在此基礎(chǔ)上作出了進(jìn)一步簡(jiǎn)化。只需要將其傳遞至Git庫(kù)，即可自動(dòng)完成構(gòu)建、發(fā)布以及文檔托管。

不過免費(fèi)文檔托管站點(diǎn)是否能夠?qū)崿F(xiàn)盈利還有待觀察——畢竟運(yùn)作這樣的站點(diǎn)需要投入成本及時(shí)間。如果站點(diǎn)無(wú)法保持一定的質(zhì)量水平，人們會(huì)選擇將文檔托管于其它平臺(tái)。而如果您喜愛自己當(dāng)前的托管方案，請(qǐng)考慮以捐款形式為其提供支持。

我認(rèn)為托管文檔服務(wù)的趨勢(shì)將進(jìn)一步持續(xù)。未來甚至有可能出現(xiàn)專門面向?qū)Ｓ熊浖母顿M(fèi)型文檔托管服務(wù)。過去十年來，開源項(xiàng)目已經(jīng)引領(lǐng)了文檔技術(shù)的發(fā)展道路，相信其將在未來繼續(xù)發(fā)揮重要作用。

原文標(biāo)題：5 trends in open source documentation   原文作者：Shaun McCance

【51CTO譯稿，合作站點(diǎn)轉(zhuǎn)載請(qǐng)注明原文譯者和出處為51CTO.com】