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

有很多不同類型的文檔：

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

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

AsciiDoc

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

—- Alan Formy-Duval

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

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

當然，我認為 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……哦，那是藍色的文本，我將懸停一下以查看它指向哪里……它指向 example.com”）。

換句話說，當我的受眾是人類讀者時，我通常會選擇 Markdown，因為它的語法簡單，但仍具有足夠的語法可以進行轉(zhuǎn)換，因此仍然是一種可接受的存儲格式。

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

—- Seth Kenlon

reStructuredText

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

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

—— Lorna Mitchell

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

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

—— Jeremy Stanley

HTML

能不用標記語言我就不用。

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

—— Rikard Grossman-Nielsen

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

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

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

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

—— Greg Pittman

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

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

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

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

<p><code>puts</code> 函數(shù)將一些文本輸出給用戶。</p>

要在文檔中格式化一段代碼塊，我使用 <pre><code>..</code></pre>，如下所示：

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

HTML 的好處在于你可以立即在任何 Web 瀏覽器中查看結(jié)果。而你使用未經(jīng)樣式化的 HTML 編寫的任何文檔都可以通過添加樣式表來美化。

—— Jim Hall

意料之外的答案：LibreOffice

在上世紀 80/90 年代，當我在 System V Unix、SunOS，最后是 Solaris 上工作時，我使用了 nroff、troff 和最終的 groff 與 mm 宏。你可以了解一下使用 groff_mm 的 MM（前提是你已經(jīng)安裝了它們）。

MM 并不是真正的標記語言，但它感覺像是。它是一套非常語義化的 troff 和 groff 宏。它具備標記語言用戶所期望的大多數(shù)功能，如標題、有序列表等等。

我的第一臺 Unix 機器上也安裝了 “Writers' Workbench”，這對我們組織中需要撰寫技術(shù)報告但沒有特別進行“引人入勝”寫作的許多人來說是一個福音。它的一些工具已經(jīng)進入了 BSD 或 Linux 環(huán)境，比如樣式（style）、用詞檢查（diction）和外觀（look）。

我還記得早在上世紀 90 年代初期，Solaris 附帶了一個標準通用標記語言（SGML）工具，也可能是我們購買了這個工具。我曾經(jīng)使用它一段時間，這可能解釋了為什么我不介意手動輸入 HTML。

我使用過很多 Markdown，我應(yīng)該說是“哪種 Markdown”，因為它有無數(shù)種風格和功能級別。正因為如此，我并不是 Markdown 的鐵桿粉絲。我想，如果我有很多 Markdown 要處理，我可能會嘗試使用一些 CommonMark 的實現(xiàn)，因為它實際上有一個正式的定義。例如，Pandoc 支持 CommonMark（以及其他幾種）。

我開始使用 AsciiDoc，相比于 Markdown，我更喜歡 AsciiDoc，因為它避免了“你使用的是哪個版本”的討論，并提供了許多有用的功能。過去，讓我對 AsciiDoc 感到困擾的是，有一段時間似乎需要安裝 Asciidoctor，這是一個我不太想安裝的 Ruby 工具鏈。但是現(xiàn)在，在我所用的 Linux 發(fā)行版中，有了更多的實現(xiàn)方式。奇怪的是，Pandoc 可以輸出 AsciiDoc，但不支持讀取 AsciiDoc。

那些嘲笑我不愿意為 AsciiDoc 安裝 Ruby 工具鏈，卻樂意安裝 Pandoc 的 Haskell 工具鏈的人……我聽到你們的笑聲了。

我羞愧地承認，我現(xiàn)在主要使用 LibreOffice。

——Chris Hermansen

現(xiàn)在就編寫文檔吧！

文檔編寫可以通過多種不同的途徑來完成，正如這里的作者們展示的那樣。對于代碼的使用方法，特別是在開源領(lǐng)域，進行文檔編寫非常重要。這確保其他人能夠正確地使用和貢獻你的代碼。同時，告訴未來的用戶你的代碼提供了什么也是明智之舉。