document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2025-03-27 02:30:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

Translated 20170307 How to make release notes count

Browse Source
This commit is contained in:
Stdio A 2017-03-08 21:00:47 +08:00
parent 55f516ecb0
commit 43c894c39d
2 changed files with 63 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
sources/tech/20170307 How to make release notes count.md
View File

@ -1,60 +0,0 @@
StdioA translating
How to make release notes count
============================================================
![How to make release notes count](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")
>Image by : opensource.com
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.
--------------------------------------------------------------------------------
作者简介：
Ben Cotton - Ben Cotton is a meteorologist by training and a high-performance computing engineer by trade. Ben works as a technical evangelist at Cycle Computing. He is a Fedora user and contributor, co-founded a local open source meetup group, and is a member of the Open Source Initiative and a supporter of Software Freedom Conservancy. Find him on Twitter (@FunnelFiasco)
--------------
via: https://opensource.com/article/17/3/how-to-improve-release-notes
作者：[Ben Cotton][a]
译者：[译者ID](https://github.com/译者ID)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [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

63
translated/tech/20170307 How to make release notes count.md Normal file
View File

@ -0,0 +1,63 @@
如何写出绝佳的发行说明
============================================================
![如何写出绝佳的发行说明](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")
>图像来源： opensource.com
恭喜！你已经准备发布你的软件包的最新版本了。现在，你需要保证你的发行说明整洁有序。当然，你可以写上“bug 修复以及性能改进”然后就算完成，但这并不能给你的用户传达任何信息。
发行说明同时用于支持和营销。它可以告诉你的的用户为什么这个发布版本对他们很重要，并可以向潜在用户展示你的软件。所以，你会希望它的内容简洁、易懂，最重要的是：确切。写发行说明的方式不止一种，所以本文只是一般提议，并不是一个命令。
人们在发行说明中写上一大段饱含愚蠢的叙事内容。如果你想这么写，那请自便——不过要记住，笑话通常是上下文相关的，你觉得很滑稽的内容，可能在你的读者眼里会变得索然无味。而且，你不能忘了写那些重要信息。
### 入门
你能从本文里学到的最简单的经验，可能是这一条：你的发行说明要写给读它的人看。对于面向用户的软件，发行说明中要注重面向用户的行为，而不是软件的内部实现。举个例子：写“点击‘取消’按钮会把你的电脑点着”，而不要写“在 cancelThatThing 函数中，thermalEventTrigger 的默认值被设为 True”。
尝试将每一条说明限制在一到两句话。发行说明的重点在于突出强调重要部分，而不是给出详尽的解释。如果你有一个公开的问题追踪页面，你可以在说明中包含问题链接（或者问题编号），这样关注此问题的读者可以通过链接来查看问题的详细内容。
你并不需要严格按照这种方法来写发行说明，但我比较喜欢下面的格式。开头写上版本号，以及发布日期。对于主要版本，你可能要再写几句话，来突出本次发布的主题。比如，“本次发布的重点在于添加了邮件客户端，因为这是所有软件的最终结束状态。”
### 兼容性更改
如果新版本中包含兼容性更改或默认行为，你最好将它们着重写出。你的用户、以及提供用户支持的人会感谢你的。在发行说明中描述出现更改的地方，如何实施更改，以及用户不执行更改会导致的后果。对于某些次要版本，你可能没有做出任何会导致不兼容的更改，那你可以省略此部分。
### 功能及改进
"
现在，你该炫耀你的软件包含的那些酷的、新奇的东西了，但是要记得站在用户的角度来写。比如，“该软件现在支持自动检测午餐照片，并将其发布到 Instagram 上。”
### 已解决的问题
没有软件是完美的，所以在这部分中你需要告诉读者们你的团队为了使这个项目更好一点而做的所有努力工作。因为那些不好的行为已经被解决了，所以应该用过去式来写这一部分。如果某个 bug 的定位很明确，那应该在这部分中写上相关信息。其它的一些项目可能也会包含这一节中所述的 bug.
### 已知问题
因为没有软件是完美的，所以永远会存在未解决的 bug. 在这一节中，你需要列出这些已知的问题。你不需要解决所有的问题；专注于影响功能的错误，如果这些是在上个版本发布后发现的，你可能需要优先解决。这一部分的文字用将来时完成。当你把这些问题解决，你只需要改变动词的时态，然后把它们移到上个部分即可。
--------------------------------------------------------------------------------
作者简介：
Ben Cotten - Ben Cotten 是一个受过专业训练的气象学家，但他现在是一位高性能计算工程师。Ben 是一位循环计算领域的布道者。它是一个 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)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [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