你喜欢哪种文档标记语言？

文档很重要，而易读的文档更重要。在开源软件世界中，文档可以告诉我们如何使用或贡献一个应用程序，就像 游戏 的规则书一样。

成都创新互联公司专业提供服务器托管服务，为用户提供五星数据中心、电信、双线接入解决方案，用户可自行在线购买服务器托管服务，并享受7*24小时金牌售后服务。

有很多不同类型的文档：

• 教程
• 操作指南
• 参考指南
• 软件架构
• 产品手册

我们向一些贡献者询问了他们的技术文档工作流程，他们更喜欢使用哪种标记语言，以及为什么会选择其中一种。以下是他们的回答。

AsciiDoc

过去几年中，Markdown 一直是我的标准语言。但最近我决定尝试一下 AsciiDoc 。这种语法并不难，我在 Linux 桌面上的 Gedit 就支持它。我计划暂时坚持使用它一段时间。

—- Alan Formy-Duval

就低语法标记语言而言，我更喜欢 AsciiDoc。我喜欢它，是因为其转换过程一致且可预测，没有令人困惑的“口味”变化 。我还喜欢将它输出为 Docbook，这是一种我信任其持久性和灵活性的标记语言，它有大量的语法标记。

但“正确”的选择往往取决于项目已经在使用什么。如果项目使用某种口味的 Markdown，我就不会使用 AsciiDoc。嗯，公平地说，我可能会使用 AsciiDoc，然后使用 Pandoc 将其转换为草莓味的 Markdown。

当然，我认为 Markdown 有其应用的时间和场合。我发现它比 AsciiDoc 更易读。AsciiDoc 中的链接是这样：

http://example.com [Example website]

而 Markdown 中的链接是这样：

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

Markdown 的语法直观，以读取 HTML 的方式呈现信息，大多数人都以相同的方式解析此类数据（“Example website……哦，那是蓝色的文本，我将悬停一下以查看它指向哪里……它指向 example.com”）。

换句话说，当我的受众是人类读者时，我通常会选择 Markdown，因为它的语法简单，但仍具有足够的语法可以进行转换，因此仍然是一种可接受的存储格式。

虽然像 AsciiDoc 这样简洁的语法看起来更令人吃惊，但如果我的受众是要解析文件的计算机，我会选择 AsciiDoc。

—- Seth Kenlon

reStructuredText

我是 代码即文档 的忠实支持者，它将开发者工具融入到内容流程中。这样可以更轻松地进行高效的审查和协作，尤其是如果工程师是贡献者。

作为一个标记语言的行家，我在 O'Reilly 写了整整一本关于 AsciiDoc 的书，还使用 Markdown 在各个平台上发布了上千篇博文。但目前，我转向使用 reStructuredText，并维护一些相关工具。

—— Lorna Mitchell

不得不提到 reStructuredText。在我大量使用 Python 编程时，它已成为我的首选。它也是 Python 长期以来用于文档源码和代码注释的标准。

与 Markdown 相比，我喜欢它不会受到非标准规范的困扰。话虽如此，当我处理更复杂的文档时，确实还得使用许多 Sphinx 的功能和扩展。

—— Jeremy Stanley

HTML

能不用标记语言我就不用。

不过，我发现 HTML 比其他标记语言更易于使用。

—— Rikard Grossman-Nielsen

对我来说，撰写文档有各种方式。这取决于文档将要放在何处，是作为网站的一部分、软件包的一部分，还是可下载的内容。

对于 Scribus 来说，其内部文档采用 HTML 格式，因为需要使用内部浏览器来访问。对于网站，可能需要使用维基语言。而对于可下载的内容，可以创建 PDF 或 EPUB 格式。

我倾向于在纯文本编辑器中编写文档。我可能会使用 XHTML，以便将这些文件导入到像 Sigil 这样的 EPUB 制作工具中。当然，对于创建 PDF，我会使用 Scribus，虽然我可能会导入用文本编辑器创建的文本文件。Scribus 具有包含图形并精确控制其布局的优势。

Markdown 从未吸引我，我也从未尝试过 AsciiDoc。

—— Greg Pittman

我目前正在使用 HTML 撰写大量文档，所以我要为 HTML 代言一下。你可以使用 HTML 创建网站或创建文档。请注意，这两者实际上并不相同 —— 当你创建网站时，大多数设计师关注的是呈现。但是当你编写文档时，技术作者应该专注于内容。

当我用 HTML 撰写文档时，我遵循 HTML 定义的标签和元素，并不关心它的外观。换句话说，我用“未经样式化”的 HTML 编写文档。稍后我总是可以添加样式表。因此，如果我需要强调文本的某一部分（比如警告），或者给单词或短语加重语气，我可能会使用  和  标签，像这样：

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

或者在段落中提供一个简短的代码示例，我可能会这样写：

puts 函数将一些文本输出给用户。

要在文档中格式化一段代码块，我使用 

..

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