如何写出绝佳的发行说明

2017-03-16
3分钟阅读时长

如何写出绝佳的发行说明

图像来源: opensource.com

恭喜你!你已经准备发布你的软件包的最新版本了。现在,你需要保证你的发行说明整洁有序。当然,你可以写上一句“bug 修复以及性能改进”然后就算完成,但这并不能给你的用户传达任何信息。

发行说明同时用于支持和营销。它可以告诉你的的用户,为什么这个发布版本对他们很重要,并可以向潜在用户展示你的软件。所以,你会希望它的内容简洁、易懂,最重要的是:目的明确。写发行说明的方式不止一种,所以本文只是一般提议,并不是一个强制要求。

现在一个流行的趋势,是将发行说明写成包含一堆蠢事的叙事文。如果你想这么写,那请自便 —— 不过要记住,笑话通常是上下文相关的,你觉得很滑稽的内容,可能在你的读者眼里会变得索然无味。而且,不要忘了将那些重要信息写进来。

入门

你能从本文里学到的最主要的经验,可能就是这一条:你的发行说明要写给读它的人看。对于面向用户的软件,发行说明中要注重面向用户的行为,而不是软件的内部实现。举个例子:写“点击‘取消’按钮会把你的电脑点着”,而不要写“在 cancelThatThing 函数中,thermalEventTrigger 的默认值被设为 True”。

尝试将每一条说明限制在一到两句话。重点在于突出强调重要部分,而不是给出详尽的解释。如果你有一个公开的问题追踪页面,你可以在说明中包含问题链接(或者问题编号),这样关注此问题的读者可以通过链接来查看问题的详细内容。

你并不需要严格按照这种方法来写发行说明,但我比较喜欢下面的格式。开头写上版本号,以及发布日期。对于主要版本,你可能要再写几句话,来突出本次发布的主题。比如,“本次发布的重点在于添加了邮件客户端,因为这是所有软件的最终结束状态。”

兼容性更改

如果新版本中包含兼容性或默认行为的变更,你最好将它们着重写出。你的用户、以及提供用户支持的人会感谢你的。在发行说明中描述会遇到行为变更的场景,如何处理变更,以及如果用户对变更不采取行动会导致的后果。对于某些次要版本,你可能没有任何会导致不兼容的变更,那你可以省略此部分。

功能及改进

现在,你该炫耀你的软件包含的那些酷的、新奇的东西了,但是要记得站在用户的角度来写。比如,“该软件现在支持自动发现午餐照片,并将其发布到 Instagram 上。”

已解决的问题

没有软件是完美的,所以在这部分中你需要告诉读者,你的团队为了使这个项目更好一点而做的所有努力工作。因为那些不好的行为已经被解决了,所以应该用过去式来写这一部分。如果某个 bug 的产生原因很明确,写上相关信息。一些项目还在文档此节中包含修复的 bug。

已知问题

因为没有软件是完美的,所以永远会存在未解决的 bug。在这一节中,你需要列出这些已知的问题。你不需要列出所有的问题;主要是影响功能的错误,尤其是那些在上个版本发布后发现的 bug。这一部分的文字用将来时态写出。当你把这些问题解决,你只需要改变动词的时态,然后把它们移到上个部分即可。


作者简介:

Ben Cotten - Ben Cotten 是一个受过专业训练的气象学家,但他现在是一位高性能计算工程师。Ben 是一位循环计算领域的布道者。他是 Fedora 的用户及贡献者,与他人一同创办了一个本地开源会议组,是开源计划的成员,还是软件自由保护的支持者。你可以在 Twitter 上找到他(@FunnelFiasco)。


译者简介:

StdioA —— Pythoner, Player.


via: https://opensource.com/article/17/3/how-to-improve-release-notes

作者:Ben Cotton 译者:StdioA 校对:jasminepeng

本文由 LCTT 原创编译,Linux中国 荣誉推出