- 作者 Andrew Lui， 文档工程师
- 原文链接：http://blogs.atlassian.com/2010/10/technical_writing_in_a_wiki_technical_communicators_explain_how_why/
- 2010-10-20
本文是Atlassian的技术写作团队专注于使用Wiki技术写作的系列文章的第一篇。在这篇文章中，我将讨论为什么Wiki是你的技术文档需求的一个好的解决方案。文章将讲解如何在Wiki上创作、出版、组织和管理文档。
当我加入Atlassian 时，Wiki已广泛应用10多年，然而之前我从未考虑使用Wiki进行文档撰写。你和我处于相同处境么？那么和我一起试试Wiki吧。Wiki并不仅仅能用于在线百科全书，它还能做很多其他的事情。
| 信息 |
|---|
“Wiki确实很不错，但不是用来撰写正式的文档的。” 有人会这么说，但这个观点是不正确的。 |
一个Wiki基本上是一个可以满足任意用户数量，能够容易地添加、修改和删除内容的网站。这使它非常适合团队在资料素材上相互协作，但是你绝不想把这混乱的想法展示给你的客户，对吗？嗯，这正是我所想的。
事情的真相是，Wiki与传统出版或CMS工具一样，能够支持的一系列全面的文档撰写。Wiki可以实现文档版本控制，内容的重用和组织，发布管理，单一原文件维护，出版等功能。在接下来的几周，我们将更详细地介绍这些主题，本文将介绍我在使用Wiki进行文档撰写时所发现的几个优势。
1） Wiki对技术作者有益
在Wiki中编写文档具有革命性的进步，如果你一直使用传统的写作工具，出版便是一个多阶段的过程。而在Wiki中，想要修复在线文档中的错误？你只需要打开页面，编辑它并保存。一切就这么简单。
同HTML或XML编辑器相比，用Wiki进行编辑更轻松。许多企业Wiki，如Confluence绑定了富文本编辑器（RTE），RTE不再需要你去处理复杂的标记。这对技术写作人员成功的进行文档撰写是一个利好消息，而不必纠结于某一丢失的破坏整个文档的标记。
Wiki不仅仅使编写和发布过程更简单。收集编写技术文档信息，通常是需要生产部经理，开发人员和我三者间的共同努力。对前期草稿进行简单地检阅，通常能获得大量有用的反馈信息。比如其他人在页面上的进行评论或更新自己的草案，那么我便可以按照他们所期望的，选择性的合并反馈或者回滚更改。
2）Wiki对你的客户有益
大部分Wiki具有传统文档工具的功能，可以帮助缺乏时间的客户找到他们所需的信息，如强大的搜索引擎，标签，导航栏/导航树等。Wiki还可以超越这些功能，为客户提供更丰富的内容。演示一个概念比解释它更容易吗？想要在文档中添加一个视频，需要描述一个复杂的过程吗？你只需要在Wiki页面中，嵌入一个流程图中即可。对许多基本的Wiki，利用插件便可实现类似的甚至更多具有创新性的功能。
如果客户需要不同格式的文档让你感到担忧，请赶紧省省吧。Wiki提供各种各样的文档导出格式选择。我们可以把文档以PDF，HTML和XML格式导出。不同的模式也可以应用到输出格式，允许文档被自定义成适合读者的格式。
在Wiki中，文档维护甚至有助于改进客户服务。我们后勤人员经常更新、添加新文档，确保客户阅读最新的信息。同时，Wiki还可以为客户提供另一个有价值的反馈渠道。页面上添加的评论经常提醒我们文档或应用程序本身存在的问题。
3）Wiki对企业有益
想到客户在你的文档Wiki中添加愤怒的评论，垃圾信息散布者在你的文档Wiki中胡闹，你感到紧张吗？这里你要从另一面考虑：顾客在Wiki中回答其他顾客的问题，外部开发人员添加代码示例，合作伙伴主动写新文档能使你的文档更充实。良好的文档Wiki有利于促成一个客户社区。良好的企业Wiki将为你提供诸如，粒度权限（granular permission），验证码（CAPTCHA），垃圾邮件过滤器工具（spam filter）之类的工具，这些工具能确保你可以在客户社区中安全的处理文档。许多组织机构已经将他们的文档保存在Wiki中——看看这个由Anne Gentle编辑的 极好的文档Wiki目录(great list of documentation Wikis)吧。
最后，从本质上讲，经过不懈努力改进的Wiki能提供比其他Wiki更多的功能。例如，当需要在Wiki中维护企业文档时，粒度权限(granular permission)功能是必要的。这是一个你不能在开源Wiki中找到的功能。但是，你会惊讶的发现Wiki解决方案是多么的具有价格竞争力，如果文档工程师可以利用上面描述的好处，将整个文档编写流程化。可能企业最终支付的费用仅仅是现在用于文档编写所支付费用的一部分。
这是值得研究的，并且我们会帮助你。在接下来的几周里，Atlassian的技术写作团队将出版了一系列的博文，每篇文章探索一个高级的主题。下周，Giles Gaskell将深入研究文档出版。请锁定我们关于在Wiki中进行技术文档编写、出版、构建和管理方面的经验分享。