文檔很重要，而易讀的文檔更重要。在開源軟件世界中，文檔可以告訴我們?nèi)绾问褂没蜇暙I(xiàn)一個應(yīng)用程序，就像 游戲 的規(guī)則書一樣。

成都創(chuàng)新互聯(lián)公司專業(yè)提供服務(wù)器托管服務(wù)，為用戶提供五星數(shù)據(jù)中心、電信、雙線接入解決方案，用戶可自行在線購買服務(wù)器托管服務(wù)，并享受7*24小時金牌售后服務(wù)。

有很多不同類型的文檔：

• 教程
• 操作指南
• 參考指南
• 軟件架構(gòu)
• 產(chǎn)品手冊

我們向一些貢獻(xiàn)者詢問了他們的技術(shù)文檔工作流程，他們更喜歡使用哪種標(biāo)記語言，以及為什么會選擇其中一種。以下是他們的回答。

AsciiDoc

過去幾年中，Markdown 一直是我的標(biāo)準(zhǔn)語言。但最近我決定嘗試一下 AsciiDoc 。這種語法并不難，我在 Linux 桌面上的 Gedit 就支持它。我計劃暫時堅持使用它一段時間。

—- Alan Formy-Duval

就低語法標(biāo)記語言而言，我更喜歡 AsciiDoc。我喜歡它，是因?yàn)槠滢D(zhuǎn)換過程一致且可預(yù)測，沒有令人困惑的“口味”變化 。我還喜歡將它輸出為 Docbook，這是一種我信任其持久性和靈活性的標(biāo)記語言，它有大量的語法標(biāo)記。

但“正確”的選擇往往取決于項(xiàng)目已經(jīng)在使用什么。如果項(xiàng)目使用某種口味的 Markdown，我就不會使用 AsciiDoc。嗯，公平地說，我可能會使用 AsciiDoc，然后使用 Pandoc 將其轉(zhuǎn)換為草莓味的 Markdown。

當(dāng)然，我認(rèn)為 Markdown 有其應(yīng)用的時間和場合。我發(fā)現(xiàn)它比 AsciiDoc 更易讀。AsciiDoc 中的鏈接是這樣：

http://example.com [Example website]

而 Markdown 中的鏈接是這樣：

[Example.com](http://example.com)

Markdown 的語法直觀，以讀取 HTML 的方式呈現(xiàn)信息，大多數(shù)人都以相同的方式解析此類數(shù)據(jù)（“Example website……哦，那是藍(lán)色的文本，我將懸停一下以查看它指向哪里……它指向 example.com”）。

換句話說，當(dāng)我的受眾是人類讀者時，我通常會選擇 Markdown，因?yàn)樗恼Z法簡單，但仍具有足夠的語法可以進(jìn)行轉(zhuǎn)換，因此仍然是一種可接受的存儲格式。

雖然像 AsciiDoc 這樣簡潔的語法看起來更令人吃驚，但如果我的受眾是要解析文件的計算機(jī)，我會選擇 AsciiDoc。

—- Seth Kenlon

reStructuredText

我是 代碼即文檔 的忠實(shí)支持者，它將開發(fā)者工具融入到內(nèi)容流程中。這樣可以更輕松地進(jìn)行高效的審查和協(xié)作，尤其是如果工程師是貢獻(xiàn)者。

作為一個標(biāo)記語言的行家，我在 O'Reilly 寫了整整一本關(guān)于 AsciiDoc 的書，還使用 Markdown 在各個平臺上發(fā)布了上千篇博文。但目前，我轉(zhuǎn)向使用 reStructuredText，并維護(hù)一些相關(guān)工具。

—— Lorna Mitchell

不得不提到 reStructuredText。在我大量使用 Python 編程時，它已成為我的首選。它也是 Python 長期以來用于文檔源碼和代碼注釋的標(biāo)準(zhǔn)。

與 Markdown 相比，我喜歡它不會受到非標(biāo)準(zhǔn)規(guī)范的困擾。話雖如此，當(dāng)我處理更復(fù)雜的文檔時，確實(shí)還得使用許多 Sphinx 的功能和擴(kuò)展。

—— Jeremy Stanley

HTML

能不用標(biāo)記語言我就不用。

不過，我發(fā)現(xiàn) HTML 比其他標(biāo)記語言更易于使用。

—— Rikard Grossman-Nielsen

對我來說，撰寫文檔有各種方式。這取決于文檔將要放在何處，是作為網(wǎng)站的一部分、軟件包的一部分，還是可下載的內(nèi)容。

對于 Scribus 來說，其內(nèi)部文檔采用 HTML 格式，因?yàn)樾枰褂脙?nèi)部瀏覽器來訪問。對于網(wǎng)站，可能需要使用維基語言。而對于可下載的內(nèi)容，可以創(chuàng)建 PDF 或 EPUB 格式。

我傾向于在純文本編輯器中編寫文檔。我可能會使用 XHTML，以便將這些文件導(dǎo)入到像 Sigil 這樣的 EPUB 制作工具中。當(dāng)然，對于創(chuàng)建 PDF，我會使用 Scribus，雖然我可能會導(dǎo)入用文本編輯器創(chuàng)建的文本文件。Scribus 具有包含圖形并精確控制其布局的優(yōu)勢。

Markdown 從未吸引我，我也從未嘗試過 AsciiDoc。

—— Greg Pittman

我目前正在使用 HTML 撰寫大量文檔，所以我要為 HTML 代言一下。你可以使用 HTML 創(chuàng)建網(wǎng)站或創(chuàng)建文檔。請注意，這兩者實(shí)際上并不相同 —— 當(dāng)你創(chuàng)建網(wǎng)站時，大多數(shù)設(shè)計師關(guān)注的是呈現(xiàn)。但是當(dāng)你編寫文檔時，技術(shù)作者應(yīng)該專注于內(nèi)容。

當(dāng)我用 HTML 撰寫文檔時，我遵循 HTML 定義的標(biāo)簽和元素，并不關(guān)心它的外觀。換句話說，我用“未經(jīng)樣式化”的 HTML 編寫文檔。稍后我總是可以添加樣式表。因此，如果我需要強(qiáng)調(diào)文本的某一部分（比如警告），或者給單詞或短語加重語氣，我可能會使用  和  標(biāo)簽，像這樣：

警告：激光！不要用你剩下的那只眼睛看向激光。

或者在段落中提供一個簡短的代碼示例，我可能會這樣寫：

puts 函數(shù)將一些文本輸出給用戶。

要在文檔中格式化一段代碼塊，我使用 

..

void
print_array(int *array, int size)
{
  for (int i = 0; i < size; i++) {
    printf("array[%d] = %d\n", i, array[i]);
  }
}