如何写出绝佳的发行说明
创始人
2024-03-01 19:09:23
0

图像来源: 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

本文由 LCTT 原创编译,Linux中国 荣誉推出

相关内容

谁懂啊?太神奇了!株洲小伙...
6月29日,株洲小伙张先生晒出自己在沙漠里突然发现自动售水机的视频...
2025-07-01 13:14:20
每周股票复盘:云天励飞(6...
截至2025年6月27日收盘,云天励飞(688343)报收于48....
2025-06-29 07:13:09
“钱不是我的,但必须取出来...
4月10日,大庆市民李某来到光大银行东风支行,称自己需要支取大额现...
2025-06-21 21:12:18
今天国际取得AI生成网页前...
金融界2025年6月18日消息,国家知识产权局信息显示,深圳市今天...
2025-06-18 10:43:16
约翰霍普金斯大学发现:AI...
这项由约翰霍普金斯大学语言和语音处理中心的Kaiser Sun、F...
2025-06-14 18:42:12

热门资讯

Helix:高级 Linux ... 说到 基于终端的文本编辑器,通常 Vim、Emacs 和 Nano 受到了关注。这并不意味着没有其他...
使用 KRAWL 扫描 Kub... 用 KRAWL 脚本来识别 Kubernetes Pod 和容器中的错误。当你使用 Kubernet...
JStock:Linux 上不... 如果你在股票市场做投资,那么你可能非常清楚投资组合管理计划有多重要。管理投资组合的目标是依据你能承受...
通过 SaltStack 管理... 我在搜索Puppet的替代品时,偶然间碰到了Salt。我喜欢puppet,但是我又爱上Salt了:)...
Epic 游戏商店现在可在 S... 现在可以在 Steam Deck 上运行 Epic 游戏商店了,几乎无懈可击! 但是,它是非官方的。...
《Apex 英雄》正式可在 S... 《Apex 英雄》现已通过 Steam Deck 验证,这使其成为支持 Linux 的顶级多人游戏之...
如何在 Github 上创建一... 学习如何复刻一个仓库,进行更改,并要求维护人员审查并合并它。你知道如何使用 git 了,你有一个 G...
2024 开年,LLUG 和你... Hi,Linuxer,2024 新年伊始,不知道你是否已经准备好迎接新的一年~ 2024 年,Lin...
什么是 KDE Connect... 什么是 KDE Connect?它的主要特性是什么?它应该如何安装?本文提供了基本的使用指南。科技日...
Opera 浏览器内置的 VP... 昨天我们报道过 Opera 浏览器内置了 VPN 服务,用户打开它可以防止他们的在线活动被窥视。不过...