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

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

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

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

做出决定

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

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

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

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