From a2035d2907651d7768ac28c1a6d1d34262c4a009 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axil@gitlab.com>
Date: Wed, 15 May 2024 07:26:41 +0000
Subject: [PATCH] Apply 1 suggestion(s) to 1 file(s)
Co-authored-by: Amy Qualls <aqualls@gitlab.com>
---
.../merge_request_templates/Documentation.md | 2 +-
doc/development/api_graphql_styleguide.md | 2 +-
.../styleguide/availability_details.md | 155 ++++++++++++++++++
.../documentation/styleguide/index.md | 144 +---------------
.../documentation/styleguide/word_list.md | 2 +-
doc/development/documentation/workflow.md | 2 +-
doc/development/ee_features.md | 2 +-
7 files changed, 164 insertions(+), 145 deletions(-)
create mode 100644 doc/development/documentation/styleguide/availability_details.md
diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md
index 77e0668b4c931..f0756cea7188b 100644
--- a/.gitlab/merge_request_templates/Documentation.md
+++ b/.gitlab/merge_request_templates/Documentation.md
@@ -15,7 +15,7 @@
- [Documentation process](https://docs.gitlab.com/ee/development/documentation/workflow.html).
- [Documentation guidelines](https://docs.gitlab.com/ee/development/documentation/).
- [Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide/).
-- [ ] If you're adding a new page, add the [product tier details](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#product-tier-details) under the H1 topic title.
+- [ ] If you're adding a new page, add the [product availability details](https://docs.gitlab.com/ee/development/documentation/styleguide/availability_details.html) under the H1 topic title.
- [ ] If you are a GitLab team member, [request a review](https://docs.gitlab.com/ee/development/code_review.html#dogfooding-the-reviewers-feature) based on:
- The documentation page's [metadata](https://docs.gitlab.com/ee/development/documentation/metadata.html).
- The [associated Technical Writer](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments).
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md
index 786b9c66a6968..3653afe042995 100644
--- a/doc/development/api_graphql_styleguide.md
+++ b/doc/development/api_graphql_styleguide.md
@@ -1176,7 +1176,7 @@ is a `HashMap` where the keys are textual descriptions, and the values are URLs.
### Subscription tier badges
If a field or argument is available to higher subscription tiers than the other fields,
-add the [tier details](documentation/styleguide/index.md#inline-tier-details) inline.
+add the [availability details inline](documentation/styleguide/availability_details.md#inline-availability-details).
For example:
diff --git a/doc/development/documentation/styleguide/availability_details.md b/doc/development/documentation/styleguide/availability_details.md
new file mode 100644
index 0000000000000..f18647e5acc87
--- /dev/null
+++ b/doc/development/documentation/styleguide/availability_details.md
@@ -0,0 +1,155 @@
+---
+info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects.
+stage: none
+group: unassigned
+description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.'
+---
+
+# Product availability details
+
+Product availability details provide information about a feature and are displayed under the topic title.
+
+Availability details include the tier, offering, status, and history.
+
+The Markdown for availability details should look like the following:
+
+```markdown
+# Topic title
+
+DETAILS:
+**Tier:** Free, Premium, Ultimate
+**Offering:** GitLab.com, Self-managed, GitLab Dedicated
+**Status:** Experiment
+
+> - [Introduced](<link-to-issue>) in GitLab 16.3.
+> - Updated in GitLab 16.4.
+```
+
+## When to add availability details
+
+Assign availability details under:
+
+- Most H1 topic titles, except the pages under `doc/development/*` and `doc/solutions/*`.
+- Topic titles for features that have different availability details than the H1 title.
+
+The H1 availability details should be the details that apply to the widest availability
+for the features on the page. For example:
+
+- If some sections apply to Premium and Ultimate, and others apply to just Ultimate,
+ the H1 **Tier:** should be `Premium, Ultimate`.
+- If some sections apply to all instances, and others apply to only `Self-managed`,
+ the **Offering:** should be `GitLab.com, Self-managed, GitLab Dedicated`
+- If some sections are Beta, and others are Experiment, the H1 **Status:** should be `Beta`.
+ If some sections are Beta, and others are generally available, then there should
+ be no **Status:** at the H1 level.
+
+## When not to add availability details
+
+Do not assign availability details:
+
+- When a feature does not have one obvious subscription tier or offering.
+ For example, if a feature applies to one tier for SaaS and a different availability for self-managed.
+
+In this case, do any or all of the following:
+
+- Use a [`NOTE`](index.md#note) alert box to describe the availability details.
+- Add availability details under other topic titles where this information makes more sense.
+- Do not add availability details under the H1.
+
+### Pages that don't need product availability details
+
+Some pages won't have availability details, because no obvious availability details apply. For example:
+
+- Tutorials.
+- Pages that compare features from different tiers.
+- Pages in the `/development` folder. These pages are automatically assigned a `Contribute` badge.
+- Pages in the `/solutions` folder. These pages are automatically assigned a `Solutions` badge.
+
+## Available product availability details
+
+For offering, use any combination of these words, in this order, separated by commas:
+
+- `GitLab.com`
+- `Self-managed`
+- `GitLab Dedicated`
+
+For example:
+
+- `GitLab.com`
+- `GitLab.com, Self-managed`
+- `Self-managed`
+- `Self-managed, GitLab Dedicated`
+
+For tier, choose one:
+
+- `Free, Premium, Ultimate`
+- `Premium, Ultimate`
+- `Ultimate`
+
+For status, choose one:
+
+- `Beta`
+- `Experiment`
+
+Generally available features should not have a status.
+
+### GitLab Duo Pro add-on
+
+The add-on belongs with other subscription tiers. Document it by using the phrase `with GitLab Duo Pro`.
+For example:
+
+```markdown
+**Tier:** Premium or Ultimate with GitLab Duo Pro
+```
+
+### Duplicating tier, offering, or status on subheadings
+
+If a subheading has the same tier, offering, or status as its parent
+topic, you don't need to repeat the information in the subheading's
+badge.
+
+For example, if the H1 heading is:
+
+```markdown
+# My title
+
+DETAILS:
+**Offering:** GitLab.com
+**Tier:** Premium, Ultimate
+```
+
+Any lower-level heading that applies to a different tier but same offering would be:
+
+```markdown
+## My title
+
+DETAILS:
+**Tier:** Ultimate
+```
+
+## Inline availability details
+
+Generally, you should not add availability details inline with other text.
+The single source of truth for a feature should be the topic where the
+functionality is described.
+
+If you do need to mention an availability details inline, write it in plain text.
+For example, for an API topic:
+
+```markdown
+IDs of the users to assign the issue to. Ultimate only.
+```
+
+For more examples, see the [REST API style guide](../restful_api_styleguide.md).
+
+## Administrator documentation for availability details
+
+Topics that are only for instance administrators should have the `Self-managed` tier.
+Instance administrator documentation often includes sections that mention:
+
+- Changing the `gitlab.rb` or `gitlab.yml` files.
+- Accessing the rails console or running Rake tasks.
+- Doing things in the Admin Area.
+
+These pages should also mention if the tasks can only be accomplished by an
+instance administrator.
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 9d966d9623e85..a57c97bad1316 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -1604,7 +1604,7 @@ For more information, see [Legal disclaimer for future features](../versions.md#
### Details
-`DETAILS:` alert boxes are used for [product tier details](#product-tier-details).
+`DETAILS:` alert boxes are used for [product availability details](#product-availability-details).
## Blockquotes
@@ -1704,147 +1704,11 @@ in the GitLab product documentation.
If a feature or product name contains spaces, don't split the name with a line break.
When names change, it is more complicated to search or grep text that has line breaks.
-### Product tier details
+### Product availability details
-Product tier details provide information about a feature and are displayed under the topic title.
+Product availability details provide information about a feature and are displayed under the topic title.
-#### When to add tier details
-
-Assign tier details under:
-
-- Most H1 topic titles, except the pages under `doc/development/*` and `doc/solutions/*`.
-- Topic titles that don't apply to the same tier as the H1.
-
-The H1 tier badge should be the badge that applies to the lowest tier for the features on the page.
-
-#### When not to add tier details
-
-Do not assign tier details:
-
-- When a feature does not have one obvious subscription tier or offering.
- For example, if a feature applies to one tier for SaaS and a different tier for self-managed.
-
-In this case, do any or all of the following:
-
-- Use a `NOTE` in an alert box to describe the tiers.
-- Add tier details under other topic titles where this information makes more sense.
-- Do not add tier details under the H1.
-
-##### Pages that don't need tier details
-
-Some pages won't have a tier badge, because no obvious tier badge applies. For example:
-
-- Tutorials.
-- Pages that compare features from different tiers.
-- Pages in the `/development` folder. These pages are automatically assigned a `Contribute` badge.
-- Pages in the `/solutions` folder. These pages are automatically assigned a `Solutions` badge.
-
-#### Available product tiers
-
-Tier details are how we refer to the information that's displayed under a topic title.
-
-Tier details include the tier, offering, status, and history.
-
-The Markdown for tier details should look like the following:
-
-```markdown
-# Topic title
-
-DETAILS:
-**Tier:** Free, Premium, Ultimate
-**Offering:** GitLab.com, Self-managed, GitLab Dedicated
-**Status:** Experiment
-
-> - [Introduced](<link-to-issue>) in GitLab 16.3.
-> - Updated in GitLab 16.4.
-```
-
-For offering, use any combination of these words, in this order, separated by commas:
-
-- GitLab.com
-- Self-managed
-- GitLab Dedicated
-
-For example:
-
-- GitLab.com
-- GitLab.com, Self-managed
-- Self-managed
-- Self-managed, GitLab Dedicated
-
-For tier, choose one:
-
-- Free, Premium, Ultimate
-- Premium, Ultimate
-- Ultimate
-
-For status, choose one:
-
-- Beta
-- Experiment
-
-Generally available features should not have a status.
-
-##### GitLab Duo Pro add-on
-
-The add-on belongs with other subscription tiers. Document it by using the phrase `with GitLab Duo Pro`.
-For example:
-
-```markdown
-**Tier:** Premium or Ultimate with GitLab Duo Pro
-```
-
-##### Duplicating tier, offering, or status on subheadings
-
-If a subheading has the same tier, offering, or status as its parent
-topic, you don't need to repeat the information in the subheading's
-badge.
-
-For example, if the heading 1 is:
-
-```markdown
-# My title
-
-DETAILS:
-**Offering:** GitLab.com
-**Tier:** Premium, Ultimate
-```
-
-Any lower-level heading that applies to a different tier but same offering would be:
-
-```markdown
-## My title
-
-DETAILS:
-**Tier:** Ultimate
-```
-
-##### Inline tier details
-
-Generally, you should not add tier details inline with other text.
-The single source of truth for a feature should be the topic where the
-functionality is described.
-
-If you do need to mention a tier inline, write it in plain text. For example,
-for an API topic:
-
-```markdown
-IDs of the users to assign the issue to. Ultimate only.
-```
-
-For more examples, see the [REST API style guide](../restful_api_styleguide.md).
-
-##### Administrator documentation tier details
-
-Topics that are only for instance administrators should have the `Self-managed` tier.
-Instance administrator documentation often includes sections that mention:
-
-- Changing the `gitlab.rb` or `gitlab.yml` files.
-- Accessing the rails console or running Rake tasks.
-- Doing things in the Admin Area.
-
-These pages should also mention if the tasks can only be accomplished by an
-instance administrator.
+Read more about [product availability details](availability_details.md).
## Specific sections
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index bed5f5a776d0f..2541495fbfa5c 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -1359,7 +1359,7 @@ The current product offerings are:
- [GitLab self-managed](#gitlab-self-managed)
- [GitLab Dedicated](#gitlab-dedicated)
-The [tier details](index.md#available-product-tiers) reflect these offerings.
+The [availability details](availability_details.md) reflect these offerings.
## older
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index ff2c1e333c474..321530ae23129 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -12,7 +12,7 @@ Documentation at GitLab follows a workflow.
Ensure your documentation includes:
-- [Product tier details](styleguide/index.md#product-tier-details).
+- [Product availability details](styleguide/availability_details.md).
- The GitLab [version](versions.md) that introduced the feature.
- Accurate [links](styleguide/index.md#links).
- Accurate [user permissions](../../user/permissions.md).
diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md
index f0b13154996b1..e65b604344e64 100644
--- a/doc/development/ee_features.md
+++ b/doc/development/ee_features.md
@@ -11,7 +11,7 @@ info: Any user with at least the Maintainer role can merge updates to this conte
- **Write tests**: As with any code, EE features must have good test coverage to prevent
regressions. All `ee/` code must have corresponding tests in `ee/`.
- **Write documentation.**: Add documentation to the `doc/` directory. Describe
- the feature and include screenshots, if applicable. Indicate [what editions](documentation/styleguide/index.md#product-tier-details)
+ the feature and include screenshots, if applicable. Indicate [what editions](documentation/styleguide/availability_details.md)
the feature applies to.
<!-- markdownlint-disable MD044 -->
- **Submit a MR to the [`www-gitlab-com`](https://gitlab.com/gitlab-com/www-gitlab-com) project.**: Add the new feature to the
--
GitLab