如何使发布说明发挥作用

恭喜！您已准备好发布最新版本的软件包。现在您需要确保您的发布说明井然有序。当然，您可以只在包装盒上写上“错误修复和性能改进”就完事大吉，但这并没有真正告诉您的用户任何信息。

发布说明既用于支持也用于营销。它们告诉您当前的用户为什么这个新版本对他们很重要，并向潜在用户展示您的软件。因此，您希望使内容清晰、易懂，最重要的是，相关。编写发布说明没有一成不变的方法，所以这只是一般建议，而不是法令。

一种流行的趋势是将发布说明写成包含大量玩笑的叙述。如果那是您喜欢的风格，那就去做吧——但请记住，笑话通常是与语境相关的，您认为搞笑的东西可能在您的读者看来完全莫名其妙。而且，当然，您不能忘记包含重要的信息。

入门

也许本文最重要的要点是为将要阅读它们的人编写发布说明。对于面向用户的软件，请关注面向用户的行为，而不是内部实现。例如，说“单击‘取消’按钮将点燃您的计算机”，而不是“thermalEventTrigger 在 cancelThatThing 函数中默认为 True。”

尽量将每条说明限制在一两句话。重点是突出重要部分，而不是给出详细的解释。如果您有公开的问题跟踪器，请包含一个链接（或至少一个问题编号），读者可以在其中找到详细信息（如果他们愿意）。

您不必以这种方式布局发布说明，但我喜欢以下格式。从版本号和发布日期开始。对于主要版本，您还可以包含几句话来突出主要主题。例如，“此版本侧重于添加电子邮件客户端，因为那是所有软件的最终状态。”

如果新版本引入了兼容性或默认行为方面的更改，请明确突出显示这些更改。您的用户会感谢您，任何提供用户支持的人也会感谢您。描述将遇到行为更改的情况，如何解决该更改，以及用户不处理该更改会发生什么。对于次要版本，您可能没有任何不兼容的更改，因此您可以省略此部分。

现在是炫耀您的软件的所有酷炫新功能的时候了，但请记住要关注用户的角度。例如，“该软件现在支持自动检测午餐图片并将其发布到 Instagram。”

没有软件是完美的，在本节中，您可以告诉读者您的团队为使项目变得更好所做的所有努力。用过去时态写这些说明，因为不良行为已经消失了。如果清楚 bug 是在哪里引入的，请包含该信息。一些项目也将文档中的 bug 包含在本节中。

因为没有软件是完美的，所以总有一些 bug 没有被消除。本节是列出这些 bug 的地方。您不必承认一切；重点关注影响功能的 bug，尤其是自上次发布以来发现的 bug。用将来时态写这些，当您解决它时，您只需更改动词时态，它就可以向上移动一个部分。