diff --git a/.gitlab/merge_request_templates/Documentation.md b/.gitlab/merge_request_templates/Documentation.md index 8081bafd39fc84ba2ec5b3501edf3bcd2e9db3f2..77e0668b4c93159efac3d9e9f46f46e52fefd472 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 badge](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#product-tier-badges) under the H1 topic title. +- [ ] 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 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 954b0a0ff5a1fc6f91a258690cb028e897992cb4..35ec6f635e840f4bbb07742ee4ea50a8f42ea6e6 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -1176,12 +1176,12 @@ 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 badge](documentation/styleguide/index.md#product-tier-badges) inline. +add the [tier details](documentation/styleguide/index.md#inline-tier-details) inline. For example: ```ruby -description: '**(ULTIMATE ALL)** Full path of a custom template.' +description: 'Full path of a custom template. Premium and Ultimate only.' ``` ## Authorization diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 332b7437084b8c64c98afc01deeda53d34d08985..9d966d9623e8561f45c376002252d315eba0b6ea 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 [tier badges](#product-tier-badges). +`DETAILS:` alert boxes are used for [product tier details](#product-tier-details). ## Blockquotes @@ -1704,22 +1704,22 @@ 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 badges +### Product tier details -Tier badges provide information about a feature and are displayed under the topic title. +Product tier details provide information about a feature and are displayed under the topic title. -#### When to add tier badges +#### When to add tier details -Assign tier badges under: +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 badges +#### When not to add tier details -Do not assign tier badges: +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. @@ -1727,10 +1727,10 @@ Do not assign tier badges: In this case, do any or all of the following: - Use a `NOTE` in an alert box to describe the tiers. -- Add tier badges under other topic titles where this information makes more sense. -- Do not add tier badges under the H1. +- 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 a tier badge +##### Pages that don't need tier details Some pages won't have a tier badge, because no obvious tier badge applies. For example: @@ -1739,13 +1739,13 @@ Some pages won't have a tier badge, because no obvious tier badge applies. For e - 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 tier badges +#### Available product tiers -Tier badges are how we refer to the information that's displayed under a topic title. +Tier details are how we refer to the information that's displayed under a topic title. -Tier badges include the tier, offering, status, and history. +Tier details include the tier, offering, status, and history. -The Markdown for tier badges should look like the following: +The Markdown for tier details should look like the following: ```markdown # Topic title @@ -1819,13 +1819,13 @@ DETAILS: **Tier:** Ultimate ``` -##### Inline tier badges +##### Inline tier details -Do not add tier badges inline with other text. +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 need to mention a tier inline, write it in plain text. For example, +If you do need to mention a tier inline, write it in plain text. For example, for an API topic: ```markdown @@ -1834,7 +1834,7 @@ 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 badges +##### 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: diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 3c835788364d9fb104e73f8fa993feac4b137fb6..9b7ab92d43e51a1157decb2e4e3d2479b643a898 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -711,7 +711,7 @@ Use lowercase for **experiment**. For example: - These features are experiments. - This experiment is ready to test. -If you must, you can use **experimental**. +If you must, you can use **experimental**. You might also want to link to [this topic](../../../policy/experiment-beta-support.md#experiment) when writing about experimental features. @@ -1359,7 +1359,7 @@ The current product offerings are: - [GitLab self-managed](#gitlab-self-managed) - [GitLab Dedicated](#gitlab-dedicated) -The [tier badges](index.md#available-product-tier-badges) reflect these offerings. +The [tier details](index.md#available-product-tiers) reflect these offerings. ## older diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 07343e9ff0fd8990dba29718678a9660431824d2..ff2c1e333c4740ac7654ddf8979610dc5947907a 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 badges](styleguide/index.md#product-tier-badges). +- [Product tier details](styleguide/index.md#product-tier-details). - 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 8cb55dde95324c0d13697ad714c09489ab2ad5b3..f0b13154996b163b63424fa9873d4736992f9af4 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-badges) + the feature and include screenshots, if applicable. Indicate [what editions](documentation/styleguide/index.md#product-tier-details) 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