wiki文档_有效使用Wiki进行文档编制的3个技巧

2023-01-02 00:00:00 wiki 文档

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文档

    原文作者:cumo3681
    原文地址: https://blog.csdn.net/cumo3681/article/details/107393871
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。

相关文章