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

By -

        去年七月,在 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

雨落清风。心向阳

发表评论

电子邮件地址不会被公开。