Merge branch 'selhorn-new-badges-style-guide' into 'master'

Updating tier badge guidance for APIs

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/142068



Merged-by: Kati Paizee <kpaizee@gitlab.com>
Approved-by: Kati Paizee <kpaizee@gitlab.com>
Reviewed-by: Kati Paizee <kpaizee@gitlab.com>
Co-authored-by: Suzanne Selhorn <sselhorn@gitlab.com>

doc/development/documentation/restful_api_styleguide.md

@@ -32,9 +32,8 @@ In the Markdown doc for a resource (AKA endpoint):
 - Every method must have a detailed [description of the response body](#response-body-description).
 - Every method must have a response body example (in JSON format).
 - If an attribute is available only to higher level tiers than the other
-  attributes, add the appropriate inline [tier badge](styleguide/index.md#product-tier-badges).
-  Put the badge in the **Attribute** column, like the
-  `**(<tier>)**` code in the following template.
+  attributes, add the appropriate tier to the description. If an attribute is
+  for Premium, include that it's also available for Ultimate.
 
 After a new API documentation page is added, [add an entry in the global navigation](site_architecture/global_nav.md#add-a-navigation-entry). [Example](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/3497).
 
@@ -65,7 +64,7 @@ Supported attributes:
 | Attribute                | Type     | Required | Description           |
 |--------------------------|----------|----------|-----------------------|
 | `attribute`              | datatype | Yes      | Detailed description. |
-| `attribute` **(<tier>)** | datatype | No       | Detailed description. |
+| `attribute`              | datatype | No       | Detailed description. |
 | `attribute`              | datatype | No       | Detailed description. |
 | `attribute`              | datatype | No       | Detailed description. |
 
@@ -75,7 +74,7 @@ response attributes:
 | Attribute                | Type     | Description           |
 |--------------------------|----------|-----------------------|
 | `attribute`              | datatype | Detailed description. |
-| `attribute` **(<tier>)** | datatype | Detailed description. |
+| `attribute`              | datatype | Detailed description. |
 
 Example request:
 
@@ -146,7 +145,7 @@ Sort the table by required attributes first, then alphabetically.
 | Attribute                    | Type          | Required | Description                                         |
 |------------------------------|---------------|----------|-----------------------------------------------------|
 | `title`                      | string        | Yes      | Title of the issue.                                 |
-| `assignee_ids` **(PREMIUM ALL)** | integer array | No       | IDs of the users to assign the issue to.            |
+| `assignee_ids`               | integer array | No       | IDs of the users to assign the issue to. Ultimate only. |
 | `confidential`               | boolean       | No       | Sets the issue to confidential. Default is `false`. |
 ```
 
@@ -155,7 +154,7 @@ Rendered example:
 | Attribute                    | Type          | Required | Description                                         |
 |------------------------------|---------------|----------|-----------------------------------------------------|
 | `title`                      | string        | Yes      | Title of the issue.                                 |
-| `assignee_ids` **(PREMIUM ALL)** | integer array | No       | IDs of the users to assign the issue to.            |
+| `assignee_ids`               | integer array | No       | IDs of the users to assign the issue to. Premium and Ultimate only. |
 | `confidential`               | boolean       | No       | Sets the issue to confidential. Default is `false`. |
 
 For information about writing attribute descriptions, see the [GraphQL API description style guide](../api_graphql_styleguide.md#description-style-guide).
@@ -181,7 +180,7 @@ Sort the table alphabetically.
 ```markdown
 | Attribute                    | Type          | Description                               |
 |------------------------------|---------------|-------------------------------------------|
-| `assignee_ids` **(PREMIUM ALL)** | integer array | IDs of the users to assign the issue to.  |
+| `assignee_ids`               | integer array | IDs of the users to assign the issue to. Premium and Ultimate only. |
 | `confidential`               | boolean       | Whether the issue is confidential or not. |
 | `title`                      | string        | Title of the issue.                       |
 ```
@@ -190,7 +189,7 @@ Rendered example:
 
 | Attribute                    | Type          | Description                               |
 |------------------------------|---------------|-------------------------------------------|
-| `assignee_ids` **(PREMIUM ALL)** | integer array | IDs of the users to assign the issue to.  |
+| `assignee_ids`               | integer array | IDs of the users to assign the issue to. Premium and Ultimate only. |
 | `confidential`               | boolean       | Whether the issue is confidential or not. |
 | `title`                      | string        | Title of the issue.                       |
 

doc/development/documentation/styleguide/index.md

@@ -1648,7 +1648,7 @@ Tier badges provide information about a feature and are displayed next to the to
 
 Assign tier badges to:
 
-- All H1 topic titles, except the pages under `doc/development/*` and `doc/solutions/*`.
+- 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.
@@ -1731,10 +1731,19 @@ Or add the status by itself:
 
 ##### Inline tier badges
 
-Do not add tier badges inline with other text, except for [API attributes](../restful_api_styleguide.md).
+Do not add tier badges 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,
+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 badges
 
 Topics that are only for instance administrators should be badged `<TIER> SELF`. Instance