Add latest changes from gitlab-org/gitlab@master

doc/development/documentation/restful_api_styleguide.md

@@ -36,7 +36,7 @@ In the Markdown doc for a resource (AKA endpoint):
   description also has both offering and tier, combine them. For
   example: _GitLab Self-Managed, Premium and Ultimate only._
 
-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).
+After a new API documentation page is added, [add an entry in the global navigation](site_architecture/global_nav.md#add-a-navigation-entry). [Examples](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/commits/main/data/navigation.yaml).
 
 ## API topic template
 
@@ -46,13 +46,21 @@ required attributes first in the table.
 ````markdown
 ## API name
 
-> - History note.
+{{</* history */>}}
+
+- History note.
+
+{{</* /history */>}}
 
 One or two sentence description of what endpoint does.
 
 ### Method title
 
-> - History note.
+{{</* history */>}}
+
+- History note.
+
+{{</* /history */>}}
 
 Description of the method.
 
@@ -105,7 +113,11 @@ for the section. For example:
 ```markdown
 ### Edit a widget
 
-> - `widget_message` [introduced](https://link-to-issue) in GitLab 14.3.
+{{</* history */>}}
+
+ - `widget_message` [introduced](https://link-to-issue) in GitLab 14.3.
+
+{{</* /history */>}}
 ```
 
 If the API or attribute is deployed behind a feature flag,
@@ -121,7 +133,11 @@ To deprecate an attribute:
 1. Add a history note.
 
    ```markdown
-   > - `widget_name` [deprecated](https://link-to-issue) in GitLab 14.7.
+   {{</* history */>}}
+
+   - `widget_name` [deprecated](https://link-to-issue) in GitLab 14.7.
+
+   {{</* /history */>}}
    ```
 
 1. Add inline deprecation text to the description.
@@ -245,8 +261,8 @@ you can use in the API documentation.
 {{< alert type="warning" >}}
 
 Do not use information for real users, URLs, or tokens. For documentation, refer to our
-relevant style guide sections on [Fake user information](styleguide/_index.md#fake-user-information),
-[Fake URLs](styleguide/_index.md#fake-urls), and [Fake tokens](styleguide/_index.md#fake-tokens).
+relevant style guide sections on [fake user information](styleguide/_index.md#fake-user-information),
+[fake URLs](styleguide/_index.md#fake-urls), and [fake tokens](styleguide/_index.md#fake-tokens).
 
 {{< /alert >}}
 
@@ -319,13 +335,13 @@ curl --request POST \
   --url "https://gitlab.example.com/api/v4/users/25/keys"
 ```
 
-The above example is run by and administrator and will add an SSH public key
-titled `ssh-key` to user's account which has an ID of 25.
+The above example adds an SSH public key titled `ssh-key` to the account of
+a user with ID 25. The operation requires administrator access.
 
 ### Escape special characters
 
-Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended
-to escape them when possible. In the example below we create a new issue which
+Spaces or slashes (`/`) can sometimes result in errors, so you should
+escape them when possible. In the example below we create a new issue which
 contains spaces in its title. Observe how spaces are escaped using the `%20`
 ASCII code.