5.0 KiB
如何写出绝佳的发行说明
图像来源： 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