如何使版本说明发挥作用

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

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

一种流行的趋势是将版本说明写成包含大量玩笑的叙述。如果那是您的风格，那就去做吧——但请记住，笑话通常是与上下文相关的，而且您认为搞笑的东西可能对您的读者来说完全摸不着头脑。而且，当然，您不能忘记包含重要的信息。

开始入门

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

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

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

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

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

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

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