Writing guideContribute to What's New or release notes

Contribute to What’s New or release notes

Follow these guidelines to ensure that your What’s New or release notes content is clear, helpful, and easy to understand.

  • Directly address your users.

    Address them using the imperative or as “you”.

    Example: Shorten your communication time when reporting issues and requesting help from Grafana Labs by grabbing a panel’s query response data and panel settings.

  • Make use of active voice or present tense.

    Example: Enable a configuration option to skip user organization and roles synchronization with your SAML provider.

  • Don’t refer to the release version, for example, “In Grafana 9, we ” or “As of now, we”.

    The What’s New or release notes are understood to be providing information for a specific release, so there is no need to repeat this information.

  • Provide high-level descriptions.

    Tell customers what goal they can accomplish or what problems they can solve with the feature. Describe the business value. Don’t go into details about how the feature works, or configuration steps.

    Link out to topics in the documentation that provide more detailed information or steps.

    Example: Use custom branding to make Grafana your observability tool by adding your own sign-in page, help links, logo, application name, and more.

    For more information, refer to [insert link to documentation].

  • Don’t refer to how the feature used to work.

    For example, don’t say “Previously, alert rules changed state when the rule was facing an error or a timeout. Now, the state does not update.”

  • For changes or updates to features, provide brief descriptions.