使用渲染语言编写文档的 5 个理由

在之前的文章中，我给出了维基是文档的绝佳选择的 5 个理由。那是一个善意的谎言。事实上，在大多数情况下，我不太喜欢维基。因此，今天我将介绍使用渲染语言发布文档的 5 个理由。

渲染文档是什么意思？本质上，它意味着不是维基。相反，您在您最喜欢的文本编辑器中编写内容，然后通过一些命令将其转换为可发布的文档。维基技术上也生成渲染文档，但我说的是与发布平台解耦的东西。现在我们已经理清了词汇，让我们来看看这些理由

1. 渲染文档提供更灵活的格式设置。这因语言而异，但通常您可以比粗体、斜体和等宽文本的组合更精细地区分命令名称和屏幕输出。
2. 渲染文档强制执行某种结构。对于松散的文档堆，逐步进行可能会很困难。因为之前没有任何内容，概念要么需要在许多页面上重新解释，要么读者必须深入链接的兔子洞。通过鼓励一点结构，渲染语言使作者能够考虑文字的流程以及读者将如何理解它们。
3. 渲染文档可以移植到其他格式。最常见的是，文档以 HTML 和 PDF 格式生成；但是，发布到 EPUB 或其他阅读器格式只是一个参数而已。这一点，以及前一点，也意味着那些想要拥有文档打印副本的人可以这样做。
4. 渲染文档可以整齐地与版本控制系统中的代码并存。这意味着所有通常的好处：分布式编辑、不同版本的分支、使用持续集成自动构建等等。
5. 渲染文档可以独立存在。在离线或低带宽情况下，必须能够从本地磁盘读取文档。

做出决定

细心的读者会注意到，其中一些好处也适用于维基，而另一些好处并非普遍适用。适合您项目的正确技术取决于您项目的性质和您的社区。具有明确发布周期的稳定项目最适合渲染文档。

拥有一个专门的文档编写团队也很有帮助。大多数用于生成文档的标记语言和工具都比维基有更高的入门门槛。临时贡献更难接收，即使是专注的潜在贡献者也可能因更陡峭的学习曲线而受挫。

如果您选择使用渲染文档作为您的首选格式，那么您必须选择一种标记语言。但那是另一天的话题了。

本文是 Rikki Endsley 协调的Doc Dish 专栏的一部分。要为本专栏投稿，请提交您的故事想法或通过 open@opensource.com 联系我们。