From 82f1cf8d8c54a59a2910c658092d10c542566976 Mon Sep 17 00:00:00 2001 From: brendamuir <100768211+brendamuir@users.noreply.github.com> Date: Mon, 15 Jan 2024 16:40:48 +0100 Subject: [PATCH] Docs: adds deprecation guidelines to toolkit (#413) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jack Baldry --- docs/sources/about-grafana-docs/index.md | 2 +- .../contribute-documentation/_index.md | 2 +- docs/sources/write/deprecate-remove/_index.md | 114 ++++++++++++++++++ docs/sources/write/reuse-content/_index.md | 2 +- 4 files changed, 117 insertions(+), 3 deletions(-) create mode 100644 docs/sources/write/deprecate-remove/_index.md diff --git a/docs/sources/about-grafana-docs/index.md b/docs/sources/about-grafana-docs/index.md index 49da62c3c..e1d464300 100644 --- a/docs/sources/about-grafana-docs/index.md +++ b/docs/sources/about-grafana-docs/index.md @@ -1,6 +1,6 @@ --- title: Introduction to documentation -menuTitle: Introduction to documentation +menuTitle: Introduction description: Learn about Grafana's documentation weight: 100 aliases: diff --git a/docs/sources/contribute-documentation/_index.md b/docs/sources/contribute-documentation/_index.md index 2630c4c8a..dc2d2e6a5 100644 --- a/docs/sources/contribute-documentation/_index.md +++ b/docs/sources/contribute-documentation/_index.md @@ -1,6 +1,6 @@ --- title: Contribute to documentation -menuTitle: Contribute to documentation +menuTitle: Contribute description: This section describes the different ways of contributing to documentation. weight: 200 aliases: diff --git a/docs/sources/write/deprecate-remove/_index.md b/docs/sources/write/deprecate-remove/_index.md new file mode 100644 index 000000000..a236590ee --- /dev/null +++ b/docs/sources/write/deprecate-remove/_index.md @@ -0,0 +1,114 @@ +--- +title: Deprecate or remove content +menuTitle: Deprecate or remove +description: Learn about deprecating or removing content in your documentation. +weight: 900 +aliases: + - /docs/writers-toolkit/write/deprecate-remove +Keywords: + - deprecate + - remove +--- + +# Deprecate or remove content + + + +**Deprecation** occurs when a feature or product is planned for removal in a future release. +In the period between deprecation and removal, it's in maintenance. + +**Removal** is when the product or feature is removed and no longer supported. + +The process for handling these scenarios varies according to how the product or feature is being phased out or maintained. + + + +You should notify users two minor releases in advance of any planned removal of a feature. +For example, if you plan to remove a feature in Grafana v9.5, then you should begin communicating that information to users in Grafana v9.3. + +To ensure that users are fully aware of the stages of deprecation for their products or features, you should: + +- Inform customers of deprecation using notes in the product's What’s New, documentation, and where necessary, in the UI. +- Inform the field by emailing [`gtm-se-field-engineering@grafana.com`](mailto:gtm-se-field-engineering@grafana.com) or by reaching out on Slack in the `#field-engineering-with-nomads` channel +- Update these notes once removal has taken place. +- Announce the deprecation in the Grafana [community slack](https://grafana.slack.com/archives/C05675Y4F) and [forum](https://community.grafana.com/). +- Inform CX and Solution Engineering. + +## Deprecation + +Scenario: "You're planning on removing the feature or product in a future release." + +Example text: + +``` +{{% admonition type="caution" %}} +Starting with , is deprecated. +It will be removed in a future release. +{{% /admonition %}} +``` + +If you know the release, enter the release instead of "future". + +### Removal + +Scenario: "You've removed a feature." + +Example text: + +``` +{{% admonition type="warning" %}} + is removed. +It is no longer deployed, enhanced, or supported. +{{% /admonition %}} +``` + +## Documentation deprecation + +Scenario: There are situations in which you may deprecate documentation along with and/or independent of feature deprecation. + +Example text: + +``` +{{% admonition type="caution" %}} + Starting with release `, the documentation will no longer be published because . +Link to documentation, if it exists. +{{% /admonition %}} +``` + + + + +Example: "As of Grafana 9.2, release notes will no longer be published, because they duplicate the content available in the What’s New document and the CHANGELOG." + + + + +## How to address deprecation + +The following process describes how to address deprecation. +This process applies when you deprecate a feature and associated documentation is also deprecated and also when you deprecate documentation independently of feature deprecation. + +You may need to add the preceding notes to both the documentation _and_ the UI. + +1. Writers, Engineers, or Product Managers determine documentation impacted by deprecation. + + + If you have a writer assigned to your team, work with your writer. + If you don't have an assigned writer, contact [Fiona Peers Artiaga](mailto:fiona.artiaga@grafana.com). + + + +1. If you don't have a writer assigned to your team, Engineers or Product Managers communicate with the Docs Squad and provide links to the impacted documentation, the rationale for the deprecation, and timing. + Post your message in the [#docs](https://raintank-corp.slack.com/archives/C5PG2JK8W) channel. + + The Docs Team triage process makes a writer aware of any pending documentation deprecation. + +1. In the PR that deprecates the documentation, writers, engineers, or Product Managers provide the rationale for deprecating the documentation in the comments using the documentation deprecation language identified in the preceding table, and if there is alternative documentation that a user can refer to, provide a link. + + GitHub automatically assigns the writer associated with those documentation as a reviewer of the PR. + + + +1. The writer either drafts the PR or reviews and approves the PR and adds a notice of the deprecation (including links, if available) in the draft What’s New document. + + diff --git a/docs/sources/write/reuse-content/_index.md b/docs/sources/write/reuse-content/_index.md index 66f0f09e4..30f669ca7 100644 --- a/docs/sources/write/reuse-content/_index.md +++ b/docs/sources/write/reuse-content/_index.md @@ -1,6 +1,6 @@ --- title: Reuse content -menuTitle: Reuse content +menuTitle: Reuse description: Learn about reusing content in your documentation. weight: 800 aliases: