最重要的文档编写惯例就是多写一些！很多程序员都轻视这些事情。但是下面两个理由可以让你明白你必须去做文档工作：
文档可以指导你的设计。写文档的最佳时机在你一行代码还没有编写就应该开始，此时你需要想想你打算做点什么。你会发现用自然语言思考程序应该完成什么功能可以促使你从更高的层次考虑软件是什么样以及她该如何工作。这个思考可以节省许多以后的时间。
文档是代码的招牌。许多程序员为他们的程序只提供了少的可怜、内容匮乏、语言差劲的蹩脚文档，这实际上等于向其他人展示说，写这个文档的程序员对潜在用户的需求也同样会粗心大意、马马虎虎。相反，好的文档则会向其他人传达出文档背后的程序员是非常聪明、专业的人。如果有一些类似的项目正在与你的竞争，一定要写出好的文档来，至少不能让潜在用户瞥了两眼你的文档后就立即否定你的项目。
这份文档虽然着眼于文档编写实践，但并不是一份专门介绍如何写出好文档的详细讲义。因此下面我们将重点介绍文档格式和编写工具的选取。
虽然开源社区长期的传统就是拥有强大的文档格式化工具，但是为数众多的文档格式仍然使得整个系统的文档支离破碎，很难用一种统一的方法全局检索和阅读文档。下面我们将先介绍各种流行的文档格式的用途以及他们的优劣，然后再给出一些编写好文档的建议。
这里将列出一些在开源软件开发群体中流行的一些文档格式。当我们文中提到“展示”标记，就是指那些控制文档显示的标记（如字体）。当我们提到“结构”标记，就是指那些描述文档结构的标记（如段落、强调标记）。当我们提到“线索化”，则是指从众多文档中萃取出可检索的关键字集合的过程，“线索化”可以帮助用户在整个文档中可靠的找出自己感兴趣的 资料。
这是最普通的文档格式，来源于UNIX系统，是一种原始的“展示”标记格式。man(1)命令提供了页显示和原始的搜索手段。这种格式不支持图象、超链接和“线索化”功能。不过这种格式转化成Postscript进行打印的效果还不错，就是转成HTML格式不太方便（主要是纯文本）。man 的相关工具在各个Linux系统中几乎都有。
手册页格式做为命令用法解释或者短小的参考文档还是不错的，对一个有经验的用户这样做可以非常节省内存。那些有着复杂用户界面和很多选项的程序会让系统负载非常重，如果交叉链接太多的文档甚至会让整个系统不堪重负。（Man手册格式没有支持超级链接）
自从1993－1994年互联网流行起来后，HTML标记格式开始流行，这种标记格式有一定的结构，也便于“展示”，还可通过网络浏览器浏览，对图象和超级链接也有支持。不过自带的“线索化”功能很有限，因此搜索引擎技术得到了大力的发展。这种格式也可以很好的被打印出来，相关的制作工具数不胜数。
HTML标记非常灵活，非常适用于各种文档。实际上她太“灵活”了，甚至可以展示Man手册页格式的信息。不过问题在于她很难自动检索，因为这种格式中太多的标记被用于描述“展示”信息，而鲜有标记描述文档的结构。
Texinfo格式是自由软件基金会推荐使用的格式。她是在强大的Tex格式引擎上建立的一套宏。拥有许多结构信息和部分表示信息。可以用Emacs浏览，或者用专门的info程序阅读。这个格式支持超级链接，但是不支持图象；无论是打印出来还是在线阅读都可以很好的“线索化”；如果你装了某个Texinfo格式的文档，该文档的信息就被整合到系统的全局目录表中。这种格式还可以很好的被转换为Postscript格式和HTML格式，相关工具在大多数Linux系统中都是预先安装好的，当然你也可以从自由软件基金会的网站上下载(http://www.gnu.org)。
Texinfo有着很好的设计，非常适合于完全字符编排的书籍和小的在线文档，但是和HTML格式一样，她也是一种两栖格式——既有表示“结构”的标记，又有表示“展示”的标记，“展示”标记给文档进一步处理带来了一些麻烦。
DocBook是一种强大且精巧的基于SGML（当前XML的前身）的标记格式。和前面几种文档结构不同，这个标记格式只包含“结构”信息，而没有“展示”信息。她可以很好的支持图片和超级链接；支持“线索化”；很易于转换成HTML格式和便于打印的Postscript格式（而且随着工具功能的增强，打印效果还可进一步提高）。该格式的文档和相关工具可以从DocBook的网站下载(http://www.docbook.org)。
DocBook在处理大而复杂的文档中表现出众；她被特意设计成可以支持各种技术文档并可以将他们用不同的输出格式“展示”出来。不过她的回溯功能非常复杂，工具也没有完全发展成熟（虽然进步很快），入门级的文档非常少而且常常写得很混乱。
2000年7月，世界一些重要的开放源码项目开发组（包括GNOME、KDE、自由软件基金会、Linux文档项目组、开源首创）在加州Monterey举行了高级首脑会议。该次会议的重要议题就是试图建立一套共同的工作惯例和共同的文档交流格式，以便为自由软件制作出更丰富、更统一的文档资源。
具体的来说，会议的目标就是要制定一种文档包的标准，使得当某文档被装入系统中后，文档包就立即被集成到整个系统的搜索数据库中，系统可以通过某种一致的手段查找、搜索各种文档。实际上GNOME和KDE组已经开始在朝这个方向努力了，大家都明白这并非是一种标记语言就可以解决的问题，而需要建立一套结构化的系统体系。
会议签署了一个意向文件，清晰的指出一些关键的开源项目正在着手或者已经采纳使用Docbook格式做为项目文档的首选格式。
与会者最后也决定了采用“Dublin core”元数据格式（一种根据库管理程序开发的与数字资料索引有关地国际标准）做为文档搜索的标准，这个标准的细节正在制定中，因此最终DocBook标记中会添加一些信息用于支持嵌入DocBook文档的Dublin Core元数据。
目标是明确的，基于索引标记和Dublin core元数据可以提高DocBook文档的自动搜索能力，从而使得DocBook的用途如虎添翼。虽然还有一些工作尚未完成，但是它们将会被不断填充进整个体系中。老的基于描述的标记语言文档所剩下的日子已经不多了。（本文档在2000年8月已经有了DocBook格式的版本）
因此新的开源项目应该注意这种动向，如果现在就采用DocBook格式的文档编写，这可以帮助他们省去以后将文档格式转档的麻烦。