2011年技术文档写作年终总结系列之二:需求跟踪

软件产品开发的特点之一就是需求的变动是比较频繁的,特别是客户定制的产品。Technical writer若想要按时交付配套技术文档,就必须紧密跟踪需求的变动。

需要说明的是,通常情况下开发和测试工作是有明确的工时计划的,但多数情况下并不会单独为配套技术文档工作考虑这个问题。换句话说,开发和测试工作完成之时,一般也就是交付技术文档的deadline。

如何处理好时间进度问题呢?关键就在于对产品需求变动的把握。明确了需求变动,你就知道大致的工作量,根据任务的deadline排出各项工作的优先级。

在新产品或新功能可用之前,可以先看看原始的需求文件。虽然多数时候原始需求文件和最终设计出来的产品/功能会有一些出入(有时候出入还挺大的),不过大致可以先了解个全景,列出一个to-do list。曾有前辈说过,有时候你甚至要能够在产品可用之前就写出用户手册(雏形)来,这是比较极端的情形,不过某种程度上也说明了规划与预估的重要性。

产品或功能的雏形出来后,即可开始动手更新用户手册了。很多时候都要用到截图,这样的话在产品完工之前就写好的用户手册,难免会有跟实际情形不太一样的截图。这种情况下,为了避免反复修改截图(说实话,截图工作是比较费心费力的),可以在写作初期将截图留空,做好标记即可。以我们使用的Docbook为例,我们可以在Docbook的源文档中先插入图片标签并为图片命名,等产品定型时才回来截图。

只看需求文件,显然不足以及时把握产品或功能的最新进展。开发和测试部门之间的沟通往来是比较频繁的,但多数时候我们并不会直接参与其中。当然了,他们是可以选择在邮件讨论过程中把我们加为抄送人,让我们知晓各种产品功能的变动,只是这样一来我们会被邮件淹没的。

幸好,我们还有个内部缺陷跟踪管理系统(用于产品的功能改进、bug修复等事件的登记),我们可以从中获得足够多的资讯。在系统中登记的每个事件,都会自动发送邮件给内部相关的收件人,基本上涵盖了开发和测试人员,而我们technical writer在公司的内部Outlook通讯薄中是属于测试部门范畴的,所以我们也可以收到缺陷跟踪管理系统发出的邮件。

为了更好地方便我们跟踪产品功能的变动,缺陷跟踪管理系统中登记的每个事件都有一个字段用于标记是否需要修改对应的用户手册。这个设计很好,可是实际使用起来效率不高,原因在于:开发/测试人员不一定能准确判断一个功能变动是否应该反映到用户手册。所以,有时候被他们标记为“必须修改”的事件,其实没必要修改用户手册,这会造成信息干扰;反过来,如果他们将本应修改用户手册的事件标记为不需要修改,那很有可能我们就会漏掉对应的功能变动。这个问题要说清楚也不是那么容易的事情,因为开发和测试人员处理问题的对象和目的毕竟和我们不太一样,也许我该抽空写份文档供他们参考下?在实际操作中,为了尽可能避免漏掉功能变动,我们会查看每一封从内部系统发出来的邮件,这个工作量可不小呢,要知道公司经常是多个产品版本和分支同时开工的,每天收到上百封邮件也是很常见的情形。

应该说,通过以上方式,我们基本上可以跟踪到大部分的产品和功能需求变动。

“2011年技术文档写作年终总结系列之二:需求跟踪”的4个回复

  1. “开发/测试人员不一定能准确判断一个功能变动是否应该反映到用户手册。”

    但是他们至少可以判断哪些改动是 bug 吧。如果是 bug,就不用更新用户手册的。这样能帮 technical writer 滤掉不少信息。

    其实还是内部沟通的问题。公司内部信息太多,杂乱无章,没有人过滤,每个人都要从一堆原始信息中过滤出自己所需的信息,造成巨大的资源浪费。更糟糕的是,一不小心就可能遗漏重要信息。

    1. 的确,每天过滤CR邮件都花了很多时间了~这个问题嘛,还需要各部门配合吧,跟Ivy姐来个研讨会啥的~

    2. 即便是BUG,有时也会涉及资料变更(例如:有些BUG涉及界面变更)。类似的不同步问题,我们之前也常遇到,这点不能完全依赖流程。遇到问题,我们也组织过多次回溯会或全员的通告,不过给别人揭短总不会让人太舒服,关系容易紧张。多跟开发同学沟通,互相熟络起来,有变更也会想着资料的。

      1. 欢迎交流~这确实是多个环节衔接的问题,不过很多时候感觉我们都是在孤军奋战。文档是弱势部门,和研发/测试沟通起来也不容易呀,只能是大家多多互相理解吧~

发表评论

电子邮件地址不会被公开。 必填项已用*标注