TranslateProject/published/201703/20170307 How to make release notes count.md

66 lines
5.0 KiB
Markdown
Raw Normal View History

如何写出绝佳的发行说明
============================================================
![如何写出绝佳的发行说明](https://opensource.com/sites/default/files/styles/image-full-size/public/images/life/rh_003784_02_os.comcareers_resume_rh1x.png?itok=CK6VJq5w "How to make release notes count")
2017-03-10 16:51:56 +08:00
*图像来源 opensource.com*
恭喜你你已经准备发布你的软件包的最新版本了。现在你需要保证你的发行说明整洁有序。当然你可以写上一句“bug 修复以及性能改进”然后就算完成,但这并不能给你的用户传达任何信息。
2017-03-10 16:51:56 +08:00
发行说明同时用于支持和营销。它可以告诉你的的用户,为什么这个发布版本对他们很重要,并可以向潜在用户展示你的软件。所以,你会希望它的内容简洁、易懂,最重要的是:目的明确。写发行说明的方式不止一种,所以本文只是一般提议,并不是一个强制要求。
现在一个流行的趋势,是将发行说明写成包含一堆蠢事的叙事文。如果你想这么写,那请自便 —— 不过要记住,笑话通常是上下文相关的,你觉得很滑稽的内容,可能在你的读者眼里会变得索然无味。而且,不要忘了将那些重要信息写进来。
### 入门
2017-03-10 16:51:56 +08:00
你能从本文里学到的最主要的经验,可能就是这一条:你的发行说明要写给读它的人看。对于面向用户的软件,发行说明中要注重面向用户的行为,而不是软件的内部实现。举个例子:写“点击‘取消’按钮会把你的电脑点着”,而不要写“在 cancelThatThing 函数中thermalEventTrigger 的默认值被设为 True”。
2017-03-10 16:51:56 +08:00
尝试将每一条说明限制在一到两句话。重点在于突出强调重要部分,而不是给出详尽的解释。如果你有一个公开的问题追踪页面,你可以在说明中包含问题链接(或者问题编号),这样关注此问题的读者可以通过链接来查看问题的详细内容。
你并不需要严格按照这种方法来写发行说明,但我比较喜欢下面的格式。开头写上版本号,以及发布日期。对于主要版本,你可能要再写几句话,来突出本次发布的主题。比如,“本次发布的重点在于添加了邮件客户端,因为这是所有软件的最终结束状态。”
### 兼容性更改
2017-03-10 16:51:56 +08:00
如果新版本中包含兼容性或默认行为的变更,你最好将它们着重写出。你的用户、以及提供用户支持的人会感谢你的。在发行说明中描述会遇到行为变更的场景,如何处理变更,以及如果用户对变更不采取行动会导致的后果。对于某些次要版本,你可能没有任何会导致不兼容的变更,那你可以省略此部分。
### 功能及改进
2017-03-10 16:51:56 +08:00
现在,你该炫耀你的软件包含的那些酷的、新奇的东西了,但是要记得站在用户的角度来写。比如,“该软件现在支持自动发现午餐照片,并将其发布到 Instagram 上。”
### 已解决的问题
2017-03-10 16:51:56 +08:00
没有软件是完美的,所以在这部分中你需要告诉读者,你的团队为了使这个项目更好一点而做的所有努力工作。因为那些不好的行为已经被解决了,所以应该用过去式来写这一部分。如果某个 bug 的产生原因很明确,写上相关信息。一些项目还在文档此节中包含修复的 bug。
### 已知问题
2017-03-10 16:51:56 +08:00
因为没有软件是完美的,所以永远会存在未解决的 bug。在这一节中你需要列出这些已知的问题。你不需要列出所有的问题主要是影响功能的错误尤其是那些在上个版本发布后发现的 bug。这一部分的文字用将来时态写出。当你把这些问题解决你只需要改变动词的时态然后把它们移到上个部分即可。
--------------------------------------------------------------------------------
作者简介:
2017-03-10 16:51:56 +08:00
Ben Cotten - Ben Cotten 是一个受过专业训练的气象学家但他现在是一位高性能计算工程师。Ben 是一位[循环计算][5]领域的布道者。他是 Fedora 的用户及贡献者,与他人一同创办了一个本地开源会议组,是开源计划的成员,还是软件自由保护的支持者。你可以在 Twitter 上找到他(@FunnelFiasco
--------------
译者简介:
[StdioA](https://www.stdioa.com/) —— Pythoner, Player.
--------------
via: https://opensource.com/article/17/3/how-to-improve-release-notes
作者:[Ben Cotton][a]
译者:[StdioA](https://github.com/StdioA)
2017-03-10 16:12:09 +08:00
校对:[jasminepeng](https://github.com/jasminepeng)
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译,[Linux中国](https://linux.cn/) 荣誉推出
[a]:https://opensource.com/users/bcotton
[1]:https://opensource.com/article/17/3/how-to-improve-release-notes?rate=81ry_1MGfmsPXV6_y_4St2DQI4XyJAqIzs4yTNtUrpA
[2]:https://opensource.com/user/30131/feed
[3]:https://opensource.com/article/17/3/how-to-improve-release-notes#comments
[4]:https://opensource.com/users/bcotton
2017-03-10 16:51:56 +08:00
[5]:https://cyclecomputing.com/