关于有效使用维基进行文档编写的 3 个技巧

图片来源：

April Killingsworth。由 Rikki Endsley 修改。CC BY-SA 2.0。

使用维基进行文档编写并不是一个新想法。无数开源项目都在这样做。如果您正在寻找一种快速编写和发布文档的方法，维基可以作为众多技术写作工具之外的可行替代方案。

话虽如此，许多维基上的文档并不总是像它们可以达到的那样有效，您可以使用一些技巧来帮助您使维基上的文档更有效、更易读。无论您是在维基上创建新文档，还是将现有文档迁移到维基上，都可以使用这些技巧。

跳出“书本”的思维模式

我从 20 多年的技术写作经验中学到一个教训：没有人喜欢阅读厚厚的手册。无论您最初是在维基上编写文档，还是将文档迁移到维基，这些维基都可能变成厚厚手册的在线版本。通常，手册中的整个章节会变成维基上的单个页面，对于读者来说，要使用浏览器浏览大量的文本和图像。

记住要摆脱书本的模式。相反，将您的文档分解成易于管理的小块。维基上有效的文档应该是一个结构化的信息块集合，而不仅仅是堆放在读者面前的一大块信息。

您可以使用“基于主题的写作”原则来实现这一点。通过基于主题的写作，文档的每个部分（例如参考资料或程序）都将成为一个单独的维基页面（或“主题”）。例如，章节的介绍是一个页面，一个程序是另一个页面，依此类推。如果您的文档中有很长的程序，您可以将它们分解成几个较短的页面。

您可能有一些简短的内容，例如单段概述或一两步程序。将这样的内容放在自己的页面上没有意义。事实上，这样的页面看起来格格不入。相反，保留这些内容在原来的位置。您最终会得到一个稍长的维基页面，但这比拥有一组看起来像是事后诸葛亮的页面要好。

导航非常重要

采用基于主题的方法可能会导致文档脱节，主题之间几乎没有任何连续性，但情况不一定如此。

您可以通过适当的导航来解决基于主题的文档的脱节性。精心设计的导航可以帮助读者轻松快速地在维基上的主题之间移动，并找到他们可能需要的任何其他信息。

良好导航的要素有哪些？它们包括：

详细的目录，读者可以在维基上的任何位置访问
一组包含指向相关内容组的链接的着陆页（例如，安装和升级程序）
每页末尾的一组指向相关信息的链接

在您的维基页面中添加链接需要大量的手工工作，但这样做是值得的，因为它使读者的体验更加顺畅。

外观也很重要

文档必须具有美学策略。它必须是友好的，不仅在写作方式上，而且在呈现方式上也是如此。它应该易于阅读，看起来有吸引力，并且看起来像是您想要参与的东西。

—Adam Hyde，Common Knowledge Foundation 联合创始人

大多数出现在维基上的文档看起来都像……嗯，它看起来就像在维基上一样。这没什么错，但读者期望更多一点，这意味着使维基本身对读者有吸引力。它应该具有您项目网站的外观和感觉。至少，考虑使用除维基默认皮肤之外的其他东西。

没有什么比标题和标题中的驼峰式命名更能体现维基的特色了。页面标题或标题中的驼峰式命名是不美观的——它在视觉上令人不悦。相反，在页面标题或标题中的单词之间添加空格。例如，不要将页面命名为“WritingASimpleMacro”，而是将其命名为“Writing a Simple Macro”。添加这些空格对于使维基页面在视觉上更具吸引力大有帮助。