如何写出绝佳的发行说明
发现 公告
![如何写出绝佳的发行说明](/data/attachment/album/201703/13/230842b151kk2crc2zk44w.png "How to make release notes count")


*图像来源： opensource.com*


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


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


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


### 入门


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


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


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


### 兼容性更改


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


### 功能及改进


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


### 已解决的问题


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


### 已知问题


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




---


作者简介：


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




---


译者简介：


[StdioA](https://www.stdioa.com/) —— Pythoner, Player.




---


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


作者：[Ben Cotton](https://opensource.com/users/bcotton) 译者：[StdioA](https://github.com/StdioA) 校对：[jasminepeng](https://github.com/jasminepeng)


本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出


OK
Congratulations! You're ready to ship the latest release of your software package. Now you need to make sure your release notes are in order. Sure, you could just slap "bug fixes and performance improvements" on the box and call it a day, but that doesn't really tell your users anything.

Release notes are for both support and marketing. They tell your current users why this new release is important to them and showcase your software to potential users. Thus, you want to make the content clear, understandable, and most importantly, relevant. There's no one way to write release notes, so this is general advice, not an edict.

One popular trend is to make the release notes a narrative that includes a lot of silliness. If that's your thing, go for it—just remember that jokes are often context-sensitive, and what you think is hilarious might be totally lost on your readers. And, of course, you can't forget to include the important information.

## Getting started

Perhaps the single most important takeaway from this article is to write your release notes for the people who will read them. For user-facing software, focus on the user-facing behavior instead of the internal implementation. For example, say, "Clicking the 'Cancel' button will light your computer on fire," instead of "thermalEventTrigger defaulted to True in the cancelThatThing function."

Try to limit each note to a sentence or two. The point is to highlight the important part, not give a detailed explanation. If you have a public issue tracker, include a link (or at least an issue number) where readers can go find details if they're so inclined.

You don't have to lay out your release notes this way, but I like the following format. Start with the version number and release date. For major releases, you might also include a few sentences to highlight the major theme. For example, "This release focuses on adding an email client, because that's the eventual end state of all software."

## Compatibility changes

If the new release introduces changes in compatibility or default behavior, highlight those explicitly. Your users will thank you, as will anyone who provides user support. Describe the cases where the behavior change will be encountered, how to address the change, and what happens if the user doesn't act on the change. For minor releases, you probably don't have any incompatible changes, so you can leave out this section.

## Features and enhancements

Now is the time to brag about all of the cool, new stuff your software does, but remember to focus on the user's perspective. For example, "The software now supports the automatic detection of pictures of lunch and posts them to Instagram."

## Issues resolved

No software is perfect, and this is the section where you tell readers about all of the hard work your team did to make the project a little better. Write these notes in the past tense, because the bad behavior is dead and gone. If it's clear where the bug was introduced, include that information. Some projects include bugs in the documentation in this section as well.

## Known issues

Because no software is perfect, there are always bugs left unsquashed. This section is the place to list those. You don't have to confess everything; focus on the bugs that impact functionality, especially if they were discovered since the last release. Write these in the future tense, and when you've addressed it, you just have to change the verb tense and it's ready to move up a section.

## 6 Comments