Add latest changes from gitlab-org/gitlab@15-2-stable-eev15.2.0-rc42

5 files changed, 47 insertions, 11 deletions

diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md
index 1f270a2b5ee..92c34c01e5d 100644
--- a/doc/development/documentation/restful_api_styleguide.md
+++ b/doc/development/documentation/restful_api_styleguide.md
@@ -66,7 +66,8 @@ Supported attributes:
 | `attribute`              | datatype | **{dotted-circle}** No | Detailed description. |
 | `attribute`              | datatype | **{dotted-circle}** No | Detailed description. |
 
-Response body attributes:
+If successful, returns [`<status_code>`](../../api/index.md#status-codes) and the following
+response attributes:
 
 | Attribute                | Type     | Description           |
 |:-------------------------|:---------|:----------------------|
@@ -103,7 +104,10 @@ for the section. For example:
 > `widget_message` [introduced](<link-to-issue>) in GitLab 14.3.
 ```
 
-## Attribute deprecation
+## Deprecations
+
+To document the deprecation of an API endpoint, follow the steps to
+[deprecate a page or topic](versions.md#deprecate-a-page-or-topic).
 
 To deprecate an attribute:
 
@@ -121,8 +125,8 @@ To deprecate an attribute:
    | `widget_name` | string | **{dotted-circle}** No | [Deprecated](<link-to-issue>) in GitLab 14.7 and is planned for removal in 15.4. Use `widget_id` instead. The name of the widget. |
    ```
 
-1. Optional. To widely announce the change, or if it's a breaking change,
-   [update the deprecations and removals documentation](../deprecation_guidelines/#update-the-deprecations-and-removals-documentation).
+To widely announce a deprecation, or if it's a breaking change,
+[update the deprecations and removals documentation](../deprecation_guidelines/#update-the-deprecations-and-removals-documentation).
 
 ## Method description
 
@@ -151,6 +155,14 @@ For information about writing attribute descriptions, see the [GraphQL API descr
 
 ## Response body description
 
+Start the description with the following sentence, replacing `status code` with the
+relevant [HTTP status code](../../api/index.md#status-codes), for example:
+
+```markdown
+If successful, returns [`200 OK`](../../api/index.md#status-codes) and the
+following response attributes:
+```
+
 Use the following table headers to describe the response bodies. Attributes should
 always be in code blocks using backticks (`` ` ``).
 
diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md
index e960a6491c7..0e8065d794f 100644
--- a/doc/development/documentation/site_architecture/folder_structure.md
+++ b/doc/development/documentation/site_architecture/folder_structure.md
@@ -85,6 +85,15 @@ place for it.
 Do not include the same information in multiple places.
 [Link to a single source of truth instead.](../styleguide/index.md#link-instead-of-repeating-text)
 
+For example, if you have code in a repository other than the [primary repositories](index.md#architecture),
+and documentation in the same repository, you can keep the documentation in that repository.
+
+Then you can either:
+
+- Publish it to <https://docs.gitlab.com>.
+- Link to it from <https://docs.gitlab.com> by adding an entry in the global navigation.
+  View [an example](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fedb6378a3c92274ba3b6031df0d34455594e4cc/content/_data/navigation.yaml#L2944).
+
 ## References across documents
 
 - Give each folder an `index.md` page that introduces the topic, and both introduces
diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md
index 05015fe7c5f..af24fbe303b 100644
--- a/doc/development/documentation/site_architecture/index.md
+++ b/doc/development/documentation/site_architecture/index.md
@@ -59,6 +59,19 @@ product, and all together are pulled to generate the docs website:
 
 Learn more about [the docs folder structure](folder_structure.md).
 
+### Documentation in other repositories
+
+If you have code and documentation in a repository other than the [primary repositories](#architecture),
+you should keep the documentation with the code in that repository.
+
+Then you can either:
+
+- [Add the repository to the list of products](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/development.md#add-a-new-product)
+  published at <https://docs.gitlab.com>.
+- [Add an entry in the global navigation](global_nav.md#add-a-navigation-entry) for
+  <https://docs.gitlab.com> that links to the documentation in that repository.
+  View [an example](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fedb6378a3c92274ba3b6031df0d34455594e4cc/content/_data/navigation.yaml#L2944-L2946).
+
 ## Assets
 
 To provide an optimized site structure, design, and a search-engine friendly
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 700d64c30d1..1af0cb72055 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -49,7 +49,7 @@ GitLab adds all troubleshooting information to the documentation, no matter how
 unlikely a user is to encounter a situation.
 
 GitLab Support maintains their own
-[troubleshooting content](../../../administration/index.md#support-team-docs)
+[troubleshooting content](../../../administration/index.md#support-team-documentation)
 in the GitLab documentation.
 
 ### The documentation includes all media types
@@ -1096,14 +1096,15 @@ copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal:
 
 ### Animated images
 
-Sometimes an image with animation (such as an animated GIF)
-can help the reader understand a complicated interaction with the user interface.
+Avoid using animated images (such as animated GIFs). They can be distracting
+and annoying for users.
 
-However, you should use them sparingly and avoid them when you can.
-Do not use them to replace written descriptions of processes or the product.
+If you're describing a complicated interaction in the user interface and want to
+include a visual representation to help readers understand it, you can:
 
-If you include an animated image, follow the same size and naming conventions we use for images. If the animated image loops, add at least a three
-second pause to the end of the loop.
+- Use a static image (screenshot) and if necessary, add callouts to emphasize an
+  an area of the screen.
+- Create a short video of the interaction and link to it.
 
 ## Videos
 
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index feb10845aea..d55cbe28d9b 100644
--- a/doc/development/documentation/testing.md
+++ b/doc/development/documentation/testing.md
@@ -361,6 +361,7 @@ To configure Vale in your editor, install one of the following as appropriate:
 - Sublime Text [`SublimeLinter-contrib-vale` package](https://packagecontrol.io/packages/SublimeLinter-contrib-vale).
 - Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server).
   You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts).
+- Atom [`atomic-vale` package](https://atom.io/packages/atomic-vale).
 - Vim [ALE plugin](https://github.com/dense-analysis/ale).
 - JetBrains IDEs - No plugin exists, but
   [this issue comment](https://github.com/errata-ai/vale-server/issues/39#issuecomment-751714451)