wiki文档

使用Wiki作为文档并不是一个新主意。 有无数的开源项目。 如果您正在寻找一种快速编写和发布文档的方法，那么Wiki可以替代现有的许多技术编写工具。

也就是说，许多Wiki上的文档并不总是像它可能那样有效，并且您可以使用一些技术来帮助您使Wiki上的文档更有效和更具可读性。 无论是在Wiki上创建新文档还是将现有文档移至一个，都可以使用这些技巧。

在“书”之外思考

我从在技术人员那里花了20多年的经验中学到了一个教训：没有人喜欢阅读厚厚的手册。 不管您是开始在Wiki上编写文档还是将文档移至Wiki，这些Wiki都可以成为厚手册的在线版本。 手册中的整个章节通常都变成Wiki上的一页，而且很多文本和图像供读者使用浏览器浏览。

记住要远离本书的模型。 相反，将您的文档分为可管理的块。 Wiki上的有效文档应该是这些块的结构化集合，而不仅仅是在读者面前丢下的大量信息。

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

您可能会有一些简短的内容，例如单段概述或一步骤或两步过程。 将这样的内容放在自己的页面上是没有意义的。 实际上，类似的页面看起来不合适。 而是将内容保留在原处。 您将获得一个稍长的Wiki页面，但是比起一组事后想到的页面要好。

导航很重要

采取基于主题的方法可能会导致文档不连贯，其中主题之间的连续性很少（如果有的话），但不一定是那样。

通过正确的导航，您可以解决基于主题的文档的不连贯性。 经过深思熟虑的导航可帮助读者轻松，快速地在Wiki上移动主题，并找到他们可能需要的其他信息。

良好导航的要素是什么？ 它们包括：

• 读者可以在Wiki上的任何位置访问的详细目录
• 一组登录页面，其中包含指向相关内容组的链接（例如，安装和升级过程）
• 每页末尾的一组指向相关信息的链接

向您的Wiki页面添加链接涉及许多手动工作，但是这样做是值得的，因为它可以使您的读者体验更加顺畅。

看起来很重要

文档必须具有美学策略。 它必须友好，不仅要以书面形式，而且要以表现形式为准。 它应该易于阅读，吸引人并且看起来像您想要参与的事物。

— Common Knowledge Foundation联合创始人亚当·海德（Adam Hyde）

Wiki上出现的大多数文档看起来……好吧，看起来就像在Wiki上一样。 没什么错，但是读者期望更多，这意味着使Wiki本身对读者具有吸引力。 它应该具有您项目网站的外观。 至少，请考虑使用Wiki的默认外观以外的其他东西。

在标题和标题中都没有像CamelCase这样的Wiki。 页面标题或标题中的CamelCase难看-它在视觉上令人讨厌。 而是在页面标题或标题中的单词之间添加空格。 例如，与其命名页面“ WritingASimpleMacro”，不如将其命名为“ Writing a Simple Macro”。 添加这些空间对于使Wiki页面更具视觉吸引力具有很长的路要走。

最后一个想法

Wiki是非常灵活和强大的工具，可用于编写和交付任何类型的文档。 要确保Wiki上的文档有效，需要付出一些努力，但是要付出额外的努力，才能使文档集中于读者的需求并使其易于使用。

翻译自: https://opensource.com/article/17/1/tips-using-wiki-documentation

wiki文档