documentation - 发行说明，有什么用？

Question

什么是发行说明以及谁阅读它们？他们应该/可以通过为当前版本吐出错误修复来实现自动化，还是需要仔细的人工编辑？那么，任何人都可以链接到关于软件发行说明的最佳实践（背后的推理）？

score 16 · Accepted Answer

错误修正和新增功能。用户将阅读它们以确定他们是否应该麻烦安装增量升级，或者等到下一个版本，因为这个版本没有添加他们需要的任何功能或修复他们正在使用的功能中的任何错误。

我想说他们至少需要一个人来阅读它们并确保每个注释都是有用的。这取决于对错误修复的评论有多好。

score 6 · Accepted Answer

这实际上取决于您的应用程序是为谁构建的以及您的组织目标。但是，我倾向于认为发行说明需要是特定版本中包含的重要关键添加、增强或修复的简明列表。

有时一个简单的错误跟踪系统信息转储就足够了，其他时候，我发现它们需要改进。

关键是通常认为发行说明是“嘿，看看我们做了什么”类型的更改列表。

score 6 · Accepted Answer

发行说明对您的测试组织（如果有的话）也很重要，以便他们知道发行版中发生了什么变化并需要测试。

score 5 · Accepted Answer

我们的发行说明是人工创建的，而不是机器创建的。涵盖三个主要主题。

版本中包含的内容（文件列表）
如何安装它
自上一个版本以来发生了什么变化（特别是如果这些变化还没有在手册中）。

第 1 项和第 2 项在不同版本之间变化不大，但需要对其进行审查。第 3 项工作量最大。

score 5 · Accepted Answer

发行说明在生产环境中也很重要。

他们帮助回答了这个古老的问题：

目前正在投入生产的到底是什么？

或者更精致的问题：这个错误实际上已经在这个版本中修复了吗？

score 4 · Accepted Answer

我习惯性地阅读发行说明。我倾向于想要一份完整的功能更改列表（或尽可能好），以便更好地使用新产品。

我想看看某些关键错误或关键安全问题何时得到解决。

score 1 · Accepted Answer

如果您的客户必须采取除正常程序之外的特殊操作以进行升级，那么发行说明和自述文件可能非常重要。警告客户/用户任何可能因安装较新补丁而自动发生的数据库升级也很有用。在我看来，发行说明和自述文件应该是为系统管理员受众编写的。因此，包括他们想知道的各种事情：重要更改的摘要、如何安装、已知的错误、您的软件可能会做的任何事情，这会让人大吃一惊，等等。

score 1 · Accepted Answer

发行说明取决于您的组织。

我可以为我的组织说话。我们使用 PDF 格式的发行说明，每次我们发布 clickonce 或后端版本。我们将发布说明发送给办公室经理。这是企业最高管理员（不仅是 IT）使用的文档。这份文件是他们了解正在发生的事情的一种方式。发生了哪些变化、正在生产中的新功能、已修复的错误以及他们可能想向用户解释的其他内容。

这是一个3到4页的文件，用简短的文字描述了这个版本中已经完成的工作。

score 0 · Accepted Answer

这当然高度依赖于应用程序/服务/诸如此类的类型，
但我发现阅读我最喜欢的开发工具等的发行说明
经常让我偶然发现我想要的漂亮、有趣甚至杀手级的功能如果我至少没有略读笔记，可能会错过.....好吧，也许不是杀手，但你明白我的意思;-)

作为大多数计算机高级用户（现在那是什么样的表达......）
我从不打扰普通文档，所以
除了点击，悬停和常见问题外，这给了我一些额外的东西......

score 0 · Accepted Answer

发行说明供测试人员和用户了解新增/更改内容。此外，在为您为客户构建的软件的新“版本”计费时，发行说明可用作支持文档。v1.31 似乎更容易关联和深入研究。

与其手动编译这两个列表，如果您可以使用您的发行说明为您执行此操作，那就太好了。

documentation - 发行说明，有什么用？

10 回答 10

Related

Reference