mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-26 21:30:55 +08:00
66 lines
5.0 KiB
Markdown
66 lines
5.0 KiB
Markdown
如何写出绝佳的发行说明
|
||
============================================================
|
||
|
||
|
||
|
||
*图像来源： opensource.com*
|
||
|
||
恭喜你！你已经准备发布你的软件包的最新版本了。现在，你需要保证你的发行说明整洁有序。当然，你可以写上一句“bug 修复以及性能改进”然后就算完成，但这并不能给你的用户传达任何信息。
|
||
|
||
发行说明同时用于支持和营销。它可以告诉你的的用户，为什么这个发布版本对他们很重要，并可以向潜在用户展示你的软件。所以，你会希望它的内容简洁、易懂，最重要的是：目的明确。写发行说明的方式不止一种，所以本文只是一般提议，并不是一个强制要求。
|
||
|
||
现在一个流行的趋势，是将发行说明写成包含一堆蠢事的叙事文。如果你想这么写，那请自便 —— 不过要记住，笑话通常是上下文相关的，你觉得很滑稽的内容，可能在你的读者眼里会变得索然无味。而且，不要忘了将那些重要信息写进来。
|
||
|
||
### 入门
|
||
|
||
你能从本文里学到的最主要的经验，可能就是这一条：你的发行说明要写给读它的人看。对于面向用户的软件，发行说明中要注重面向用户的行为，而不是软件的内部实现。举个例子：写“点击‘取消’按钮会把你的电脑点着”，而不要写“在 cancelThatThing 函数中，thermalEventTrigger 的默认值被设为 True”。
|
||
|
||
尝试将每一条说明限制在一到两句话。重点在于突出强调重要部分，而不是给出详尽的解释。如果你有一个公开的问题追踪页面，你可以在说明中包含问题链接（或者问题编号），这样关注此问题的读者可以通过链接来查看问题的详细内容。
|
||
|
||
你并不需要严格按照这种方法来写发行说明，但我比较喜欢下面的格式。开头写上版本号，以及发布日期。对于主要版本，你可能要再写几句话，来突出本次发布的主题。比如，“本次发布的重点在于添加了邮件客户端，因为这是所有软件的最终结束状态。”
|
||
|
||
### 兼容性更改
|
||
|
||
如果新版本中包含兼容性或默认行为的变更，你最好将它们着重写出。你的用户、以及提供用户支持的人会感谢你的。在发行说明中描述会遇到行为变更的场景，如何处理变更，以及如果用户对变更不采取行动会导致的后果。对于某些次要版本，你可能没有任何会导致不兼容的变更，那你可以省略此部分。
|
||
|
||
### 功能及改进
|
||
|
||
现在，你该炫耀你的软件包含的那些酷的、新奇的东西了，但是要记得站在用户的角度来写。比如，“该软件现在支持自动发现午餐照片，并将其发布到 Instagram 上。”
|
||
|
||
### 已解决的问题
|
||
|
||
没有软件是完美的，所以在这部分中你需要告诉读者，你的团队为了使这个项目更好一点而做的所有努力工作。因为那些不好的行为已经被解决了，所以应该用过去式来写这一部分。如果某个 bug 的产生原因很明确，写上相关信息。一些项目还在文档此节中包含修复的 bug。
|
||
|
||
### 已知问题
|
||
|
||
因为没有软件是完美的，所以永远会存在未解决的 bug。在这一节中，你需要列出这些已知的问题。你不需要列出所有的问题；主要是影响功能的错误，尤其是那些在上个版本发布后发现的 bug。这一部分的文字用将来时态写出。当你把这些问题解决，你只需要改变动词的时态，然后把它们移到上个部分即可。
|
||
|
||
--------------------------------------------------------------------------------
|
||
|
||
作者简介：
|
||
|
||
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)
|
||
校对：[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
|
||
[5]:https://cyclecomputing.com/
|