最重要的良好文档实践是真正地写一些文档！ 太多程序员忽略了这一点。 但这里有两个充分的理由来这样做：
你的文档可以成为你的设计文档。 编写文档的最佳时机是在你键入任何一行代码之前，当你在思考你想做什么的时候。 你会发现，用自然语言描述你希望程序如何工作的过程，能让你专注于关于程序应该做什么以及如何工作的高层次问题。 这可能会为你节省大量的后续工作。
你的文档是你代码质量的广告。 许多人将程序中糟糕、简略或粗劣的文档视为程序员粗心大意或不关心潜在用户需求的标志。 另一方面，良好的文档传达了智慧和专业的信息。 如果你的程序必须与其他程序竞争，最好确保你的文档至少和他们的文档一样好，否则潜在用户可能会看都不看你一眼就放弃。
即使这样做是可行的，本 HOWTO 也不是技术写作课程的合适场所。 因此，我们将在这里重点介绍用于编写和呈现文档的格式和工具。
尽管 Unix 和开源社区长期以来拥有强大的文档格式化工具的传统，但不同格式的过多意味着文档往往是分散的，用户难以以连贯的方式浏览或索引。 我们将总结常用文档格式的用途、优点和缺点。 然后，我们将为良好的实践提出一些建议。
以下是目前在开源开发者中广泛使用的文档标记格式。 当我们谈到“演示”标记时，我们指的是显式控制文档外观的标记（例如字体更改）。 当我们谈到“结构化”标记时，我们指的是描述文档逻辑结构的标记（例如章节分隔符或强调标记）。 当我们谈到“索引”时，我们指的是从文档集合中提取可搜索的主题指针集合的过程，用户可以使用这些指针可靠地在整个集合中找到感兴趣的材料。
最常见的格式，继承自 Unix，是一种原始的演示标记形式。 man(1) 命令提供了一个分页器和一个石器时代的搜索工具。 不支持图像或超链接或索引。 渲染到 Postscript 以进行打印的效果相当好。 完全不能很好地渲染到 HTML（基本上是纯文本）。 Linux 系统上预装了工具。
对于命令摘要或旨在唤起有经验用户记忆的简短参考文档，Man page 格式还不错。 对于具有复杂界面和许多选项的程序，它开始显得吃力，如果你需要维护一组具有丰富交叉引用的文档（标记仅具有微弱且通常不使用的超链接支持），它会完全崩溃。
自 1993-1994 年 Web 爆炸式增长以来，越来越常见。 标记部分是结构化的，大部分是演示的。 可以通过任何 Web 浏览器浏览。 对图像和超链接的良好支持。 内置的索引功能有限，但存在并广泛部署了良好的索引和搜索引擎技术。 渲染到 Postscript 以进行打印的效果相当好。 HTML 工具现在随处可用。
HTML 非常灵活，适用于多种文档。 实际上，它太灵活了； 它与 man page 格式有相同的问题，即很难自动索引，因为很多标记描述的是演示而不是文档结构。
Texinfo 是自由软件基金会使用的文档格式。 它是基于强大的 TeX 格式引擎的一组宏。 主要是结构化的，部分是演示的。 可以通过 Emacs 或独立的 info 程序浏览。 对超链接的良好支持，但不支持图像。 对打印和在线形式都有良好的索引； 当你安装 Texinfo 文档时，会自动将指向它的指针添加到可浏览的“dir”文档中，其中列出了你系统上的所有 Texinfo 文档。 渲染到优秀的 Postscript 和可用的 HTML。 Texinfo 工具预装在大多数 Linux 系统上，并且可以在 自由软件基金会 网站上获得。
Texinfo 是一个好的设计，非常适合排版书籍以及小型在线文档，但像 HTML 一样，它有点像两栖动物——标记部分是结构化的，部分是演示的，演示部分为渲染带来了问题。
DocBook 是一种大型、精细的标记格式，基于 SGML（更新的版本基于 XML）。 与此处描述的其他格式不同，它是完全结构化的，没有演示标记。 对图像和超链接的极佳支持。 对索引的良好支持。 很好地渲染到 HTML，可以接受地渲染到 Postscript 以进行打印（随着工具的发展，质量正在提高）。 工具和文档可在 DocBook 网站上获得。
DocBook 非常适合大型、复杂的文档； 它专门设计用于支持技术手册并以多种输出格式渲染它们。 它的主要缺点是冗长。 幸运的是，现在有好的工具和入门级文档可用； 有关介绍，请参阅 DocBook 解密 HOWTO。
DocBook 的一个严重缺点是它的标记相当繁重且笨拙。 最近一个巧妙的变通方法是 AsciiDOC。 此工具是 DocBook 的前端，具有更简单、更自然的输入语法。 用户根本不需要了解 DocBook，但仍然可以获得这些工具的几乎全部功能。
AsciiDOC（通常以它附带的格式化程序的全部小写名称来称呼）最近在以前转移到 DocBook 的项目中看到了非常快速的普及。
自 2000 年以来，文档实践一直在变化，当时一些关键的开源项目组（包括 Linux 内核项目、GNOME、KDE、自由软件基金会和 Linux 文档项目）就一种比传统 Unix 的面向打印的工具更友好的 Web 方法达成了一致。 自 XML-DocBook 工具链在 2001 年中期达到生产状态以来，今天的最佳实践是：
以 XML-DocBook 或 asciidoc 维护你的文档主文件。 即使你的 man pages 也可以是 DocBookRefEntry文档。 有一个非常好的 HOWTO 介绍了编写手册页，其中解释了你的用户期望看到的章节和组织结构。
发布 XML 或 asciidoc 主文件。 此外，如果用户的系统没有 xmlto(1)（自 7.3 以来在所有 Red Hat 发行版上都是标准配置），则发布通过对你的主文件运行转换获得的 troff 源文件。 你的软件发行版的安装程序应以正常方式安装这些文件，但如果人们想编写文档补丁，则应指导他们使用 XML/asciidoc 文件。
很容易告诉 make(1) 使生成的 man 文件保持最新。 只需在你的 makefile 中执行类似以下的操作：
foo.1: foo.xml xmlto man foo.xml |
如果你使用的是 asciidoc，则类似以下内容应该可以满足需求：
foo.1: foo.txt asciidoc --backend=docbook foo.txt xmlto man foo.xml |
从你的主文件生成 XHTML（使用 xmlto xhtml，或直接使用 asciidoc），并使其在你的项目网页上可用，人们可以在那里浏览它，以决定是否下载你的代码并加入你的项目。
对于将 troff 格式的旧文档转换为 DocBook，请查看 doclifter。 如果你不愿意放弃使用 man 源文件作为主文件格式，至少尝试清理它们，以便 doclifter 可以自动将它们转换为 XML。