2011年技术文档写作年终总结系列之三:发布说明的维护

套用一句流行的话:曾经,我以为发布说明(release notes)是很不起眼的东西,直到我膝盖中了一箭。

刚来公司时,前辈让我整理一下产品的发布说明,当时我不以为然,不就是列出一些功能变动么。可是,实际操作一遍后,我才明白这真是个细活,简直比针线活还要细(这个貌似夸张了点……好吧,我虽然没干过针线活,不过看过,总可以了吧?)。

首先是格式问题。你得用非常简洁,但又是普通用户看得懂的语言来描述(即所谓的jargonfree:毕竟这类文档不是给技术人员看的)。其实中文版发布说明还好,毕竟是母语,即便写得言简意赅的,大致也能看得懂。英文就要斟酌一番啦,有一些业内的惯例要遵循,例如通常不会使用主谓宾结构完整的句子来描述一个功能变动(除非是情形很复杂)。想看看现成的例子?可以参考已经成为版本帝的Firefox,人家的发布说明样式就非常之精细:

The complete list of bugs fixed in Firefox 9.0

举个例子,系统加了某个新功能,你可以这么写:

There is a new feature XXX.

也可以这么写:

New: XXX.

或:

Added support for XXX.

显然,后两者简洁得多,且含义足够明确。

其次是内容问题。发布说明目的在于描述不同版本之间的功能变动,这意味着你要收集到足够全面的信息才能写好这类文档。我刚来公司时,貌似前辈的做法是在产品正式发布前几天,让所有测试MM把自己总结的功能变动整理一下发给我们,然后由我们进行编辑和完善。一开始我觉得这个方式还OK,因为测试MM每个人自己负责的模块她们最清楚了,多了或者少了哪些功能,她们大致是知道的。问题是,貌似MM们平时也没怎么整理功能变动的,临时就在邮件里写几个大概的功能变动就发邮件过来了。显然,仅仅靠这些信息,我们没法保证发布说明的内容完整度。

发布说明是针对终端用户的,要求细化到每个菜单名、位置的变动,而不仅仅是一个大概的功能描述。于是,正如《2011年技术文档写作年终总结系列之二:需求跟踪》一文中所提过的,后来我主要依赖内部的缺陷跟踪管理系统来收集信息。功能变动一旦得到确认,且写进用户手册之后,即可将其记录到到发布说明中。

还有一个版本问题,这个是比较令人纠结的。理论上,发布说明也有自己的版本变动,应该和对应产品版本保持一致。例如,某个产品从版本3.1升级到3.2,那么对应的发布说明必须准确反映这两个版本之间的变动。大版本之间变动其实还好办,一般都比较明确。问题是,对开发和测试人员来讲,两个大版本之间可以存在多个细分的版本,但我们却很难做到。例如,年初发布了3.1,过了两个月,有新客户的发布,对应的版本当然跟年初不太一样了,有可能是3.1.2。然后这个客户在年底升级到3.2,我们该如何给出发布说明呢?理想情况是,我们要能够随时给出3.1.2到3.2之间的功能变动记录。可是,实际情况是,没法做得这么精细,只能有需要时才手动编辑:在公司内部的虚拟客户环境版本中检查一遍系统,找出3.1到3.1.2之间的功能(即客户所用的旧版系统已有的功能),然后从现有的3.1~3.2发布说明中去除这些功能。一般来讲,我们的发布说明平时也只能是在大版本之间进行维护。没法细化发布说明的原因有很多,例如,版本3.1到3.2之间可能存在两个并行开发的版本,有一些功能是先在高版本实现,然后迁移回低版本;也有可能,高版本最后演变成分支了。总之,举这个简单的例子就是想说明,开发和测试可以实现很多个精细的产品版本,但对应的功能变动,仅靠technical writer是没法100%予以跟踪和记录的。所以,每次给出发布说明,基本上我们都要对照实际的产品(新版和旧版)检查几遍,删除不该加进去的内容,或者补充尚未包含的内容,这是纯手工活。

另外一个有意思的话题就是,发布说明是否要包含bug fixes内容,即缺陷修改记录。就公司的实际情形而言,我没有把bug fixes写进发布说明,原因如下:
1)对于即将升级到新版的客户来说,他们更期望看到的是有关新功能或改进的介绍;
2)如果真的要包括bug fixes,那发布说明文档的长度将吓死人。不信?还是去看看Firefox的发布说明吧。我真心觉得没必要将开发和测试关注的内部bug fixes写进发布说明,不然维护工作量太大了。