From ed8725863db9710cb0eae6be9f6a7bf0c054e886 Mon Sep 17 00:00:00 2001 From: Eve Meelan <81647476+Eve832@users.noreply.github.com> Date: Fri, 17 Nov 2023 12:34:58 -0800 Subject: [PATCH] first pass at What's new update. Not sure about the content I commented out. --- .../contribute-release-notes/index.md | 64 +++++++++++++++---- 1 file changed, 51 insertions(+), 13 deletions(-) diff --git a/docs/sources/contribute-documentation/contribute-release-notes/index.md b/docs/sources/contribute-documentation/contribute-release-notes/index.md index b941d0ea3..5c1761422 100644 --- a/docs/sources/contribute-documentation/contribute-release-notes/index.md +++ b/docs/sources/contribute-documentation/contribute-release-notes/index.md @@ -14,19 +14,56 @@ keywords: This topic explains the decisions and actions associated with collecting, writing, and publishing What's new content. -> **Note:** This topic is only relevant for internal Grafana Labs contributors. +{{% admonition type="note" %}} +This topic is only relevant for internal Grafana Labs contributors. +{{% /admonition %}} ## What's new doc development process -Developing directly in Markdown reduces errors and removes a manual (toilsome and error-prone) step, by creating, editing, discussing, and publishing in the same format from which we will publish in GitHub, using the Grafana repository. - -Consider adding an image, though be aware that we will not maintain them, as the document reflects a "point in time." If you need to add an image, refer to [Image, diagram, and screenshot guidelines]({{< relref "../../write/image-guidelines" >}}). - -### When the prior release is complete +What’s new content is published to our site through the website content management system (CMS), and can be accessed here: [](). + +Because this platform is meant to be used by the entire organization, by default anyone can contribute and publish to What’s new, without the need for approval. **Quality assurance will need to be a conversation within and between contributing teams and internal stakeholders**, but there are some best practice guidelines described in the last two sections of this topic. + +Release notes should be entered into the CMS 2-4 weeks before the feature is available, depending on the size of the product or feature. This gives the GTM team time for promotion and enablement. For Grafana versioned releases, have your content entered in the CMS by the cut off date communicated by the delivery team. For more information, see the RADS guidelines. + +When you’re ready to add a What’s new entry, complete the following steps: +1. Fill out the fields: + * FEATURE NAME - Short headline for the improvement. For example, “Grafana OnCall integration for Alerting.” + * DATE - Date and time (UTC) that you want this note published. If you’ve opened a review PR, it will need to be merged before the date/time. If you enter a date that has passed, the note will publish immediately with that date. + * CONTACT - First and last name. The contents of this field are not publicly viewable. + * TAGS (OPTIONAL) - Select category tags that users can use to filter their view. Select as many as apply. + * CLOUD AVAILABILITY - Select the stage of the feature’s cloud release. + * CLOUD OFFERING - Select which account types have access to the feature. + * SELF-MANAGED EDITIONS - Select the on-premises offering(s) where this feature is available. + * BODY - Include an overview of the feature and the problem it solves. If you want to view some best practices around what to write here, see Writing guidelines for what’s new below. + Add any images and a link to your public Youtube video here. + If you need more information on adding an image, refer to: Image, diagram, and screenshot guidelines. + * FEATURE TOGGLE NAME (OPTIONAL) - Exact name of the feature toggle for this feature, if one exists. For example, publicDashboards. + * DOCUMENTATION URL (OPTIONAL) - URL to the public documentation for this feature. + * GRAFANA URL PATH (OPTIONAL) - URL path to the feature in a Grafana Cloud stack. For example, /alerting/notifications. + * INTERNAL INFORMATION (OPTIONAL) - Information for Grafana Labs employees only. For example, ProductDNA, slack channel, FAQ, training docs or videos. Used for training and internal announcements. + +1. Request a review (optional). + Select this option to open a PR in the website repository for review. +1. Click **Save**. When the note is saved, you can select **In review** from the **Status:** dropdown menu. + The review PR will appear in the website repository. Note that the Documentation Team does not automatically review these requests; teams that create What’s new entries are responsible for determining their own review process. However, there are two weekly Office Hours meetings offered by the Documentation Team that you’re welcome to attend for guidance and assistance: + * Docs squad office hours (early) + * Docs squad office hours (late) + If you open a PR, ensure that it’s merged in time for your feature release date. + +1. Preview your entry and ensure that it looks the way you want it to. + For Grafana versioned releases, the content will be collected by [someone] and published in the versioned What’s new at a later date. + + + + + + + -## How to determine if content belongs in a What's new document +## How to determine if content belongs in What's new Grafana publishes a What's new [docs page](/docs/grafana/latest/whatsnew/) and [blog post](/blog/2022/11/29/grafana-9.3-release/) along with every minor and major release. + These posts are popular, and a good way for users to learn about the exciting new things we've released. What's new also drives our go-to-market enablement: we train the field and make videos on the topics in What's new.