十大技巧助你成为文档圣手

        去年七月，在 OKFestival 渡过一整周后，我设法抽出足够的精力出席 Write the Docs Unconferences 会议。我仅参加了一天，但是因为 Paul Adams 在此次会议中提出“我们应该提出一些措施来帮助文档团队更具创造性“而很有价值。Paul Adams 是一名自由软件倡导者以及 KDAB 公司工程类的董事。

• 学会批注风格并坚持下去

你所学习的批注语言要让你的团队考虑是否能满足你所有的需求，尤其是要选择能毫不费力就能从批注转换到正式输出格式的工具。对于编辑工具来说那是无所谓的，可以让他们选择自己喜欢的文本编辑器或着编辑一份维基（wiki）。这取决于团队的表现。

• 总是使用转换输入的工具链

工具的关键在于总能自动的产生输出。最理想的是一条命令就能多次产生你所需要的各种格式的文档。

• 将最后的文档格式按你的用户需求生成

大多数项目以 HTML 网页文档或者一份 PDF 文档结束。

• 为文档定义一份风格指南并按指南执行

定义所有的事情，包括语言细微的差异，标题的写法，或者说在整篇文章中代词的用法等。

• 总是要有翻译

也许你现在不需要翻译，但之后可能会需要。不是每个人都说英语或汉语。最终你都会想到要翻译。我们曾经就想过将文档按日语翻译。当你在使用标注和工具链的时候最好就考虑翻译。（请看“文档翻译 5 技巧”）。

• 翻译要基于原始文档

假如你是用英语写文档，那么让你其他所有的翻译都基于英语。这样在修改文档时能保持一定简便。

• 制定语言特有风格指南

这点既要求程序性语言也要求自然语言。某些语言在写办公型文档可能出现部分代词的特殊用法。形成团队的一份程序语言特有风格指南非常有利于保持文档统一。

• 对文档做质量检验

如果在你的文档中有使用说明，它们就需要被检查，如是否存在单个字符的改变破坏使用说明的问题。另外，要回顾新的文档。这一点对安装说明和 API 文档尤其重要，因为这类文档很容易出错并令最终的用户感到沮丧。

• 更新和存档文档要有规则

如果你的文档过时了，将其存档并从移除搜索引擎检索。当新的文档有老版本中不存在的特性时，一定要有一个清晰的通知。如果文档是你代码的一部分，而且只有在发布新版本时文档才会被更新，那么针对于老版本的补丁文档也是应该要有的。

• 文档必须要有反馈机制

最间单的方式就是为文档添加一个漏洞跟踪反馈分类。

总而言之，写文档最重要的是建立一种文档文化。文档不是事后的一份随想，是需要一个逐步修改发行的过程。一个仅能通过文档团队才能知道所需要文档新特性的过程。虽然事实上，如果能找到一位开发者乐意支持文档项目那可就再好不过了。但我更愿授权给他们而不是麻烦他们。因为这样做更有用，否则可能加重他们的负担。举个例来说，不要把文档相关的漏洞归咎于他们，并给他们干涉文档特性的权利。因为他们正处于文档编辑中。

看到这里的你是否想到了其他建议呢？如果有，就请在下方评论让我们知道吧。

原文链接：http://opensource.com/business/15/7/10-tips-better-documentation