文档非常重要，原因有很多。可读的文档更为重要。在开源软件的世界中，文档说明了如何使用应用程序或为其做贡献。它就像一个游戏的规则手册。
文档有很多不同的类型
-
教程
-
操作指南
-
参考指南
-
软件架构
-
产品手册
我们询问了一些 Opensource.com 的贡献者关于他们的技术文档工作流程、他们首选的标记语言以及他们为什么可能选择一种语言而不是另一种语言。以下是他们的看法。
AsciiDoc
在过去的几年里，Markdown一直是我的标准语言。但最近我决定尝试一下 AsciiDoc。语法并不难，而且我 Linux 桌面上的 Gedit 支持它。我计划坚持使用一段时间。
就低语法标记而言，我更喜欢 AsciiDoc。我喜欢它，因为它的转换过程是一致且可预测的，没有令人惊讶的“风格”变体来混淆事物。我也喜欢它输出到 Docbook，这是一种标记繁重的语法，我相信它的持久性和灵活性。
但“正确”的选择往往是项目已经使用的东西。如果一个项目使用草莓味 Markdown，我不会用 AsciiDoc 编写。好吧，公平地说，我可能会用 AsciiDoc 编写，然后使用 Pandoc 将其转换为草莓味 Markdown。
我确实认为 Markdown 有它的时间和地点。我确实觉得它比 AsciiDoc 更易读。AsciiDoc 中的链接
http://example.com[Example website]Markdown 中的链接
[Example.com](http://example.com)Markdown 语法是直观的，它以我大多数人在阅读 HTML 时解析相同数据的方式传递信息（“示例网站……哦，那是蓝色文本，我将鼠标悬停在它上面以查看它去哪里……它去 example.com”）。
换句话说，当我的受众是人类读者时，我经常选择 Markdown，因为它的语法很微妙，但它有足够的语法使其可以转换，所以它仍然是一种不错的存储格式。
AsciiDoc，即使它非常简洁，看起来也更可怕。
如果我的受众是计算机，它将解析文件，我选择 AsciiDoc。
reStructuredText
我是 代码即文档 的忠实粉丝，以及它如何将开发人员工具引入内容工作流程。这使得进行高效的审查和协作变得更容易，特别是如果工程师是贡献者。
我也是一个标记语言鉴赏家，曾在 O'Reilly 用 AsciiDoc 编写了整本书，为各种平台编写了大量 Markdown，包括我博客上的数千篇文章。目前，我是一个 reStructuredText 转换者，并维护该领域的一些工具。
必须提及 reStructuredText。这是我目前的首选，因为我做了很多 Python 编程。它也是 Python 多年来文档源和代码注释的标准。
我喜欢它没有像 Markdown 那样遭受那么多非标准扩散的困扰。 也就是说，在处理更复杂的文档时，我确实使用了大量的 Sphinx 功能和扩展。
HTML
如果我不必使用标记语言，我很少使用。
不过，我发现 HTML 比其他标记语言更容易使用。
对我来说，制作文档的方法有很多种。这取决于文档的用途，是在网站上、作为软件包的一部分还是可下载的东西。
对于 Scribus，内部文档是 HTML 格式，因为内部浏览器用于访问它。在网站上，您可能需要使用 Wiki 语言。对于可下载的东西，您可能会创建 PDF 或 EPUB。
我倾向于在纯文本编辑器中编写文档。我可能会使用 XHTML，这样我就可以将这些文件导入到像 Sigil 这样的 EPUB 制作器中。当然，Scribus 是我制作 PDF 的首选应用程序，尽管我可能会导入使用文本编辑器创建的文本文件。Scribus 的优势在于可以包含并精确控制图形的位置。
Markdown 从未引起我的注意，我也从未尝试过 AsciiDoc。
我现在正在用 HTML 编写大量文档，所以我将为 HTML 做宣传。您可以使用 HTML 创建网站，或创建文档。请注意，这两者实际上并不相同——当您创建网站时，大多数设计师都关注演示。但是当您编写文档时，技术作家应该专注于内容。
当我用 HTML 编写文档时，我坚持 HTML 定义的标签和元素，我并不担心它会是什么样子。换句话说，我用“无样式”HTML 编写文档。我可以稍后添加样式表。因此，如果我需要使文本的某些部分更强（例如警告）或强调单词或短语，我可能会使用 <strong> 和 <em> 标签，像这样
<p><strong>Warning: Lasers!</strong> Do <em>not</em> look into laser with remaining eye.</p>或者为了在段落正文中提供一个简短的代码示例，我可能会写
<p>The <code>puts</code> function prints some text to the user.</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 浏览器查看结果。您用无样式 HTML 编写的任何文档都可以在以后通过添加样式表使其更漂亮。
意外之选：LibreOffice
回到 80 年代和 90 年代，当我在 System V Unix、SunOS 以及最终的 Solaris 工作时，我将 mm 宏与 nroff, troff 以及最终的 groff 一起使用。阅读关于使用 groff_mm 的 MM（前提是您已安装它们。）
MM 实际上不是一种标记语言，但感觉像是一种。它是一组非常语义化的 troff 和 groff 宏。它具有标记语言用户期望的大多数东西——标题、编号列表等等。
我的第一台 Unix 机器上也有 Writers' Workbench，这对我们组织中许多必须撰写技术报告但“写作方式”并不特别吸引人的人来说是一个福音。它的一些工具已进入 BSD 或 Linux——style、diction 和 look。
我还记得一个标准的通用标记语言 (SGML) 工具，它随 Solaris 一起提供，或者可能是我们在 90 年代初为 Solaris 购买的。我使用了一段时间，这可以解释为什么我不介意输入自己的 HTML。
我相当多地使用了 Markdown，但话虽如此，我也应该说“哪种 Markdown”，因为有无尽的风格和功能级别。我不是 Markdown 的忠实粉丝，因为这个原因。我想如果我有很多 Markdown 要做，我可能会尝试倾向于 CommonMark 的某些实现，因为它实际上有一个正式的定义。例如，Pandoc 支持 CommonMark（以及其他几种）。
我开始使用 AsciiDoc，我更喜欢它而不是 Markdown，因为它避免了“您使用的是哪个版本”的对话，并提供了许多有用的东西。过去在 AsciiDoc 方面让我放慢速度的是，在一段时间内，它似乎需要安装 Asciidoctor——一个 Ruby 工具链，我并不急于安装。但现在至少在我的 Linux 发行版中有更多的实现。奇怪的是，Pandoc 会发出 AsciiDoc，但不会读取它。
那些嘲笑我不想要用于 AsciiDoc 的 Ruby 工具链，但对用于 Pandoc 的 Haskell 工具链感到满意的人……我听到你们的声音了。
我很惭愧地承认，我现在主要使用 LibreOffice。
立即编写文档！
正如这里的作者所展示的那样，可以通过许多不同的途径来实现文档编写。记录如何使用您的代码非常重要，尤其是在开源中。这确保了其他人可以正确使用您的代码并为其做出贡献。告诉未来的用户您的代码提供了什么也是明智之举。
4 条评论