Add latest changes from gitlab-org/gitlab@13-5-stable-eev13.5.0-rc42

7 files changed, 454 insertions, 302 deletions

diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md
index a4a6ee2fa0f..0f03ceeb4b5 100644
--- a/doc/development/documentation/feature_flags.md
+++ b/doc/development/documentation/feature_flags.md
@@ -52,7 +52,7 @@ For feature flags disabled by default, if they can be used by end users:
   do not say anything about it.
 - Say whether it's recommended for production use.
 - Document how to enable and disable it.
-- Add a warning to the user saying that the feature is disabled.
+- Add a warning to the user saying that the feature might be disabled.
 
 For example, for a feature disabled by default, disabled on GitLab.com, cannot
 be enabled for a single project, and is not ready for production use:
@@ -250,7 +250,7 @@ be enabled by project, and is ready for production use:
 > - [Introduced](link-to-issue) in GitLab 12.0.
 > - It's [deployed behind a feature flag](<replace with path to>/user/feature_flags.md), enabled by default.
 > - It's enabled on GitLab.com.
-> - It can be enabled or disable for a single project.
+> - It can be enabled or disabled for a single project.
 > - It's recommended for production use.
 > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)**
 
diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md
new file mode 100644
index 00000000000..11e6b159359
--- /dev/null
+++ b/doc/development/documentation/graphql_styleguide.md
@@ -0,0 +1,92 @@
+---
+type: reference, dev
+stage: none
+group: Development
+info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
+description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation."
+---
+
+# GraphQL API
+
+GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference
+information is generated in our [GraphQL reference](../../api/graphql/reference/index.md).
+
+However, it's helpful to include examples on how to use GraphQL for different
+*use cases*, with samples that readers can use directly in the
+[GraphiQL explorer](../api_graphql_styleguide.md#graphiql).
+
+This section describes the steps required to add your GraphQL examples to
+GitLab documentation.
+
+## Add a dedicated GraphQL page
+
+To create a dedicated GraphQL page, create a new `.md` file in the
+`doc/api/graphql/` directory. Give that file a functional name, such as
+`import_from_specific_location.md`.
+
+## Start the page with an explanation
+
+Include a page title that describes the GraphQL functionality in a few words,
+such as:
+
+```markdown
+# Search for [substitute kind of data]
+```
+
+Describe the search. One sentence may be all you need. More information may
+help readers learn how to use the example for their GitLab deployments.
+
+## Include a procedure using the GraphiQL explorer
+
+The GraphiQL explorer can help readers test queries with working deployments.
+Set up the section with the following:
+
+- Use the following title:
+
+  ```markdown
+  ## Set up the GraphiQL explorer
+  ```
+
+- Include a code block with the query that anyone can include in their
+  instance of the GraphiQL explorer:
+
+  ````markdown
+  ```graphql
+  query {
+    <insert queries here>
+  }
+  ```
+  ````
+
+- Tell the user what to do:
+
+  ```markdown
+  1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`.
+  1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
+  1. Select **Play** to get the result shown here:
+  ```
+
+- Include a screenshot of the result in the GraphiQL explorer. Follow the naming
+  convention described in the [Save the image](styleguide.md#save-the-image) section of the Documentation style guide.
+- Follow up with an example of what you can do with the output. Make sure the
+  example is something that readers can do on their own deployments.
+- Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md).
+
+## Add the GraphQL example to the global navigation
+
+You should include a link for your new document in the global navigation (the list on the
+left side of the documentation website). To do so, open a second MR, against the
+[GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/).
+
+We store our global navigation in the [`default-nav.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/default-nav.yaml) file, in the
+`content/_data` subdirectory. You can find the GraphQL section under the
+following line:
+
+```yaml
+- category_title: GraphQL
+```
+
+Be aware that CI tests for that second MR will fail with a bad link until the
+main MR that adds the new GraphQL page is merged. Therefore, only merge the MR against the
+[`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) repository after the content has
+been merged and live on `docs.gitlab.com`.
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index d6f24d6374d..e51f966ee6e 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -1,4 +1,7 @@
 ---
+stage: none
+group: Documentation Guidelines
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 description: Learn how to contribute to GitLab Documentation.
 ---
 
@@ -52,9 +55,9 @@ docs-only merge requests using the following guide:
 
 [Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community.
 
-To ensure that GitLab docs are current, there are special processes and responsibilities for all [feature changes](feature-change-workflow.md), that is development work that impacts the appearance, usage, or administration of a feature.
+To ensure that GitLab docs are current, there are special processes and responsibilities for all [feature changes](workflow.md), that is development work that impacts the appearance, usage, or administration of a feature.
 
-However, anyone can contribute [documentation improvements](improvement-workflow.md) that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab.
+However, anyone can contribute [documentation improvements](workflow.md) that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab.
 
 ## Markdown and styles
 
@@ -128,7 +131,7 @@ The following metadata should be added when a page is moved to another location:
 
 - `redirect_to`: The relative path and filename (with an `.md` extension) of the
   location to which visitors should be redirected for a moved page.
-  [Learn more](#changing-document-location).
+  [Learn more](#move-or-rename-a-page).
 - `disqus_identifier`: Identifier for Disqus commenting system. Used to keep
   comments with a page that's been moved to a new URL.
   [Learn more](#redirections-for-pages-with-disqus-comments).
@@ -156,17 +159,18 @@ Nanoc layout), which will be displayed at the top of the page if defined:
   [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/lib/helpers/reading_time.rb)
   to calculate the reading time based on the number of words.
 
-## Changing document location
+## Move or rename a page
+
+Moving or renaming a document is the same as changing its location. This process
+requires specific steps to ensure that visitors can find the new
+documentation page, whether they're using `/help` from a GitLab instance or by
+visiting <https://docs.gitlab.com>.
 
-Changing a document's location requires specific steps to ensure that
-users can seamlessly access the new doc page, whether they are accessing content
-on a GitLab instance domain at `/help` or at <https://docs.gitlab.com>. Be sure to assign a
-technical writer if you have any questions during the process (such as
-whether the move is necessary), and ensure that a technical writer reviews this
-change prior to merging.
+Be sure to assign a technical writer to a page move or rename MR. Technical
+Writers can help with any questions and can review your change.
 
-If you indeed need to change a document's location, do not remove the old
-document, but instead replace all of its content with the following:
+To change a document's location, don't remove the old document, but instead
+replace all of its content with the following:
 
 ```markdown
 ---
@@ -176,14 +180,18 @@ redirect_to: '../path/to/file/index.md'
 This document was moved to [another location](../path/to/file/index.md).
 ```
 
-Where `../path/to/file/index.md` is usually the relative path to the old document.
+Replace `../path/to/file/index.md` with the relative path to the old document.
+
+The `redirect_to` variable supports both full and relative URLs; for example:
 
-The `redirect_to` variable supports both full and relative URLs, for example
-`https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`.
-It ensures that the redirect will work for <https://docs.gitlab.com> and any `*.md` paths
-will be compiled to `*.html`.
-The new line underneath the front matter informs the user that the document
-changed location and is useful for someone that browses that file from the repository.
+- `https://docs.gitlab.com/ee/path/to/file.html`
+- `../path/to/file.html`
+- `path/to/file.md`
+
+The redirect works for <https://docs.gitlab.com>, and any `*.md` paths are
+changed to `*.html`. The description line following the `redirect_to` code
+informs the visitor that the document changed location if the redirect process
+doesn't complete successfully.
 
 For example, if you move `doc/workflow/lfs/index.md` to
 `doc/administration/lfs.md`, then the steps would be:
@@ -208,9 +216,8 @@ For example, if you move `doc/workflow/lfs/index.md` to
    git grep -n "lfs/lfs_administration"
    ```
 
-NOTE: **Note:**
-If the document being moved has any Disqus comments on it, there are extra steps
-to follow documented just [below](#redirections-for-pages-with-disqus-comments).
+1. If the document being moved has any Disqus comments on it, follow the steps
+   described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments).
 
 Things to note:
 
@@ -241,7 +248,8 @@ using the old URL as value. For example, let's say we moved the document
 available under `https://docs.gitlab.com/my-old-location/README.html` to a new location,
 `https://docs.gitlab.com/my-new-location/index.html`.
 
-Into the **new document** front matter, we add the following:
+Into the **new document** front matter, we add the following information. You must
+include the file name in the `disqus_identifier` URL, even if it's `index.html` or `README.html`.
 
 ```yaml
 ---
@@ -249,9 +257,6 @@ disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html'
 ---
 ```
 
-Note: it is necessary to include the file name in the `disqus_identifier` URL,
-even if it's `index.html` or `README.html`.
-
 ## Merge requests for GitLab documentation
 
 Before getting started, make sure you read the introductory section
@@ -267,9 +272,8 @@ represents a good-faith effort to follow the template and style standards,
 and is believed to be accurate.
 
 Further needs for what would make the doc even better should be immediately addressed
-in a follow-up MR or issue.
+in a follow-up merge request or issue.
 
-NOTE: **Note:**
 If the release version you want to add the documentation to has already been
 frozen or released, use the label `~"Pick into X.Y"` to get it merged into
 the correct release. Avoid picking into a past release as much as you can, as
@@ -392,8 +396,7 @@ You will need at least Maintainer permissions to be able to run it.
 
 ![Manual trigger a docs build](img/manual_build_docs.png)
 
-NOTE: **Note:**
-You will need to push a branch to those repositories, it doesn't work for forks.
+You must push a branch to those repositories, as it doesn't work for forks.
 
 The `review-docs-deploy*` job will:
 
@@ -410,17 +413,16 @@ minutes and it should appear online, otherwise you can check the status of the
 remote pipeline from the link in the merge request's job output.
 If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
 
-TIP: **Tip:**
-Someone with no merge rights to the GitLab projects (think of forks from
-contributors) cannot run the manual job. In that case, you can
-ask someone from the GitLab team who has the permissions to do that for you.
-
-NOTE: **Note:**
 Make sure that you always delete the branch of the merge request you were
 working on. If you don't, the remote docs branch won't be removed either,
 and the server where the Review Apps are hosted will eventually be out of
 disk space.
 
+TIP: **Tip:**
+Someone with no merge rights to the GitLab projects (think of forks from
+contributors) cannot run the manual job. In that case, you can
+ask someone from the GitLab team who has the permissions to do that for you.
+
 ### Troubleshooting review apps
 
 In case the review app URL returns 404, follow these steps to debug:
@@ -462,7 +464,7 @@ If you want to know the in-depth details, here's what's really happening:
 The following GitLab features are used among others:
 
 - [Manual actions](../../ci/yaml/README.md#whenmanual)
-- [Multi project pipelines](../../ci/multi_project_pipeline_graphs.md)
+- [Multi project pipelines](../../ci/multi_project_pipelines.md)
 - [Review Apps](../../ci/review_apps/index.md)
 - [Artifacts](../../ci/yaml/README.md#artifacts)
 - [Specific runner](../../ci/runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects)
@@ -668,7 +670,7 @@ build pipelines:
      ```
 
      We recommend installing the version of `markdownlint-cli` currently used in the documentation
-     linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L38).
+     linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420).
 
 1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using
    `brew` for macOS, run:
@@ -678,7 +680,7 @@ build pipelines:
    ```
 
    We recommend installing the version of Vale currently used in the documentation linting
-   [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L16).
+   [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419).
 
 In addition to using markdownlint and Vale at the command line, these tools can be
 [integrated with your code editor](#configure-editors).
diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md
new file mode 100644
index 00000000000..b12578b5d98
--- /dev/null
+++ b/doc/development/documentation/restful_api_styleguide.md
@@ -0,0 +1,180 @@
+---
+type: reference, dev
+stage: none
+group: Development
+info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
+description: "Writing styles, markup, formatting, and other standards for GitLab's RESTful APIs."
+---
+
+# RESTful API
+
+REST API resources are documented in Markdown under
+[`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each
+resource has its own Markdown file, which is linked from `api_resources.md`.
+
+When modifying the Markdown, also update the corresponding
+[OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi)
+if one exists for the resource. If not, consider creating one. Match the latest
+[OpenAPI 3.0.x specification](https://swagger.io/specification/). (For more
+information, see the discussion in this
+[issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16023#note_370901810).)
+
+In the Markdown doc for a resource (AKA endpoint):
+
+- Every method must have the REST API request. For example:
+
+  ```plaintext
+  GET /projects/:id/repository/branches
+  ```
+
+- Every method must have a detailed [description of the parameters](#method-description).
+- Every method must have a cURL example.
+- Every method must have a response body (in JSON format).
+
+## API topic template
+
+The following can be used as a template to get started:
+
+````markdown
+## Descriptive title
+
+One or two sentence description of what endpoint does.
+
+```plaintext
+METHOD /endpoint
+```
+
+| Attribute   | Type     | Required | Description           |
+|:------------|:---------|:---------|:----------------------|
+| `attribute` | datatype | yes/no   | Detailed description. |
+| `attribute` | datatype | yes/no   | Detailed description. |
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/endpoint?parameters"
+```
+
+Example response:
+
+```json
+[
+  {
+  }
+]
+```
+````
+
+## Method description
+
+Use the following table headers to describe the methods. Attributes should
+always be in code blocks using backticks (`` ` ``).
+
+```markdown
+| Attribute | Type | Required | Description |
+|:----------|:-----|:---------|:------------|
+```
+
+Rendered example:
+
+| Attribute | Type   | Required | Description         |
+|:----------|:-------|:---------|:--------------------|
+| `user`    | string | yes      | The GitLab username. |
+
+## cURL commands
+
+- Use `https://gitlab.example.com/api/v4/` as an endpoint.
+- Wherever needed use this personal access token: `<your_access_token>`.
+- Always put the request first. `GET` is the default so you don't have to
+  include it.
+- Wrap the URL in double quotes (`"`).
+- Prefer to use examples using the personal access token and don't pass data of
+  username and password.
+
+| Methods                                         | Description                                           |
+|:-------------------------------------------     |:------------------------------------------------------|
+| `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. |
+| `--request POST`                                | Use this method when creating new objects             |
+| `--request PUT`                                 | Use this method when updating existing objects        |
+| `--request DELETE`                              | Use this method when removing existing objects        |
+
+## cURL Examples
+
+The following sections include a set of [cURL](https://curl.haxx.se) examples
+you can use in the API documentation.
+
+CAUTION: **Caution:**
+Do not use information for real users, URLs, or tokens. For documentation, refer to our
+relevant style guide sections on [Fake user information](styleguide.md#fake-user-information),
+[Fake URLs](styleguide.md#fake-urls), and [Fake tokens](styleguide.md#fake-tokens).
+
+### Simple cURL command
+
+Get the details of a group:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/gitlab-org"
+```
+
+### cURL example with parameters passed in the URL
+
+Create a new project under the authenticated user's namespace:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?name=foo"
+```
+
+### Post data using cURL's `--data`
+
+Instead of using `--request POST` and appending the parameters to the URI, you
+can use cURL's `--data` option. The example below will create a new project
+`foo` under the authenticated user's namespace.
+
+```shell
+curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
+```
+
+### Post data using JSON content
+
+NOTE: **Note:**
+In this example we create a new group. Watch carefully the single and double
+quotes.
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups"
+```
+
+### Post data using form-data
+
+Instead of using JSON or urlencode you can use multipart/form-data which
+properly handles data encoding:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "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.
+
+### 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
+contains spaces in its title. Observe how spaces are escaped using the `%20`
+ASCII code.
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
+```
+
+Use `%2F` for slashes (`/`).
+
+### Pass arrays to API calls
+
+The GitLab API sometimes accepts arrays of strings or integers. For example, to
+exclude specific users when requesting a list of users for a project, you would
+do something like this:
+
+```shell
+curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users"
+```
diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md
index 22d97a9e2cf..9fce9b4e4b3 100644
--- a/doc/development/documentation/site_architecture/global_nav.md
+++ b/doc/development/documentation/site_architecture/global_nav.md
@@ -324,7 +324,6 @@ There are three main considerations on the logic built for the nav:
   - `https://docs.gitlab.com/ee/`
   - `https://docs.gitlab.com/omnibus/`
   - `https://docs.gitlab.com/runner/`
-  - `https://docs.gitlab.com/debug/`
   - `https://docs.gitlab.com/*`
 - [EE-only](#ee-only-docs): documentation only available in `/ee/`, not on `/ce/`, e.g.:
   - `https://docs.gitlab.com/ee/user/group/epics/`
@@ -342,8 +341,8 @@ all the nav links to other pages:
 <% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %>
 ```
 
-For instance, for `https://docs.gitlab.com/ce/user/index.html`,
-`dir` == `ce`, and for `https://docs.gitlab.com/omnibus/README.html`,
+For instance, for `https://docs.gitlab.com/ee/user/index.html`,
+`dir` == `ee`, and for `https://docs.gitlab.com/omnibus/README.html`,
 `dir` == `omnibus`.
 
 #### Default URL
diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md
index 98bb116aba6..d04d34ff786 100644
--- a/doc/development/documentation/site_architecture/release_process.md
+++ b/doc/development/documentation/site_architecture/release_process.md
@@ -121,10 +121,11 @@ versions (stable branches `X.Y` of the `gitlab-docs` project):
    pipelines succeed:
 
    NOTE: **Note:**
-   The `release-X-Y` branch needs to be present locally, otherwise the Rake
-   task will abort.
+   The `release-X-Y` branch needs to be present locally,
+   and you need to have switched to it, otherwise the Rake task will fail.
 
    ```shell
+   git checkout release-X-Y
    ./bin/rake release:dropdowns
    ```
 
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 984c64b9e9e..6075124ef40 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -251,7 +251,7 @@ The table below shows what kind of documentation goes where.
 | `doc/legal/`          | Legal documents about contributing to GitLab.                                                                                           |
 | `doc/install/`        | Contains instructions for installing GitLab.                                                                                            |
 | `doc/update/`         | Contains instructions for updating GitLab.                                                                                              |
-| `doc/topics/`         | Indexes per topic (`doc/topics/topic-name/index.md`): all resources for that topic.                                                     |
+| `doc/topics/`         | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic.                                                     |
 
 ### Work with directories and files
 
@@ -287,9 +287,8 @@ The table below shows what kind of documentation goes where.
 1. The `doc/topics/` directory holds topic-related technical content. Create
    `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary.
    General user- and admin- related documentation, should be placed accordingly.
-1. The directories `/workflow/`, `/university/`, and `/articles/` have been
-   *deprecated* and the majority their documentation has been moved to their
-   correct location in small iterations.
+1. The `/university/` directory is *deprecated* and the majority of its documentation
+   has been moved.
 
 If you are unsure where to place a document or a content addition, this should
 not stop you from authoring and contributing. You can use your best judgment and
@@ -369,7 +368,7 @@ create an issue or an MR to propose a change to the user interface text.
   - milestones
   - reorder issues
   - runner, runners, shared runners
-  - a to-do, to-dos
+  - a to-do item, to dos
 - *Some features are capitalized*, typically nouns naming GitLab-specific
   capabilities or tools. For example:
   - GitLab CI/CD
@@ -410,7 +409,7 @@ Use forms of *sign in*, instead of *log in* or *login*. For example:
 Exceptions to this rule include the concept of *single sign-on* and
 references to user interface elements. For example:
 
-- To sign in to product X, enter your credentials, and then click **Log in**.
+- To sign in to product X, enter your credentials, and then select **Log in**.
 
 ### Inclusive language
 
@@ -418,8 +417,11 @@ We strive to create documentation that is inclusive. This section includes
 guidance and examples in the following categories:
 
 - [Gender-specific wording](#avoid-gender-specific-wording).
+  (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).)
 - [Ableist language](#avoid-ableist-language).
+  (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).)
 - [Cultural sensitivity](#culturally-sensitive-language).
+  (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).)
 
 We write our developer documentation with inclusivity and diversity in mind. This
 page is not an exhaustive reference, but describes some general guidelines and
@@ -433,12 +435,16 @@ a gender-neutral pronoun.
 
 Avoid the use of gender-specific pronouns, unless referring to a specific person.
 
+<!-- vale gitlab.InclusionGender = NO -->
+
 | Use                               | Avoid                           |
 |-----------------------------------|---------------------------------|
 | People, humanity                  | Mankind                         |
 | GitLab Team Members               | Manpower                        |
 | You can install; They can install | He can install; She can install |
 
+<!-- vale gitlab.InclusionGender = YES -->
+
 If you need to set up [Fake user information](#fake-user-information), use
 diverse or non-gendered names with common surnames.
 
@@ -446,6 +452,8 @@ diverse or non-gendered names with common surnames.
 
 Avoid terms that are also used in negative stereotypes for different groups.
 
+<!-- vale gitlab.InclusionAbleism = NO -->
+
 | Use                    | Avoid                |
 |------------------------|----------------------|
 | Check for completeness | Sanity check         |
@@ -455,6 +463,8 @@ Avoid terms that are also used in negative stereotypes for different groups.
 | Active/Inactive        | Enabled/Disabled     |
 | On/Off                 | Enabled/Disabled     |
 
+<!-- vale gitlab.InclusionAbleism = YES -->
+
 Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language)
 in the Google Developer Style Guide.
 
@@ -464,13 +474,57 @@ Avoid terms that reflect negative cultural stereotypes and history. In most
 cases, you can replace terms such as `master` and `slave` with terms that are
 more precise and functional, such as `primary` and `secondary`.
 
+<!-- vale gitlab.InclusionCultural = NO -->
+
 | Use                  | Avoid                 |
 |----------------------|-----------------------|
 | Primary / secondary  | Master / slave        |
 | Allowlist / denylist | Blacklist / whitelist |
 
+<!-- vale gitlab.InclusionCultural = YES -->
+
 For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02).
 
+### Fake user information
+
+You may need to include user information in entries such as a REST call or user profile.
+**Do not** use real user information or email addresses in GitLab documentation. For email
+addresses and names, do use:
+
+- **Email addresses**: Use an email address ending in `example.com`.
+- **Names**: Use strings like `example_username`. Alternatively, use diverse or
+  non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`,
+  or `Alex Garcia`.
+
+### Fake URLs
+
+When including sample URLs in the documentation, use:
+
+- `example.com` when the domain name is generic.
+- `gitlab.example.com` when referring to self-managed instances of GitLab.
+
+### Fake tokens
+
+There may be times where a token is needed to demonstrate an API call using
+cURL or a variable used in CI. It is strongly advised not to use real tokens in
+documentation even if the probability of a token being exploited is low.
+
+You can use the following fake tokens as examples:
+
+| Token type            | Token value                                                        |
+|:----------------------|:-------------------------------------------------------------------|
+| Private user token    | `<your_access_token>`                                              |
+| Personal access token | `n671WNGecHugsdEDPsyo`                                             |
+| Application ID        | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
+| Application secret    | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` |
+| CI/CD variable        | `Li8j-mLUVA3eZYjPfd_H`                                             |
+| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd`                                         |
+| Shared runner token   | `6Vk7ZsosqQyfreAxXTZr`                                             |
+| Trigger token         | `be20d8dcc028677c931e04f3871a9b`                                   |
+| Webhook secret token  | `6XhDroRcYPM5by_h-HLY`                                             |
+| Health check token    | `Tu7BgjR9qeZTEyRzGG2P`                                             |
+| Request profile token | `7VgpS4Ax5utVD2esNstz`                                             |
+
 ### Language to avoid
 
 When creating documentation, limit or avoid the use of the following verb
@@ -529,6 +583,7 @@ tenses, words, and phrases:
 - Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example:
   - Use *primary* and *secondary* for database and server relationships.
   - Use *allowlist* and *denylist* to describe access control lists.
+- Avoid the word *please*. For details, see [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please).
 
 ### Word usage clarifications
 
@@ -832,8 +887,10 @@ When creating tables of lists of features (such as whether or not features are
 available to certain roles on the [Permissions](../../user/permissions.md#project-members-permissions)
 page), use the following phrases (based on the SVG icons):
 
-- *No*: **{dotted-circle}** No
-- *Yes*: **{check-circle}** Yes
+| Option | Markdown                 | Displayed result       |
+|--------|--------------------------|------------------------|
+| No     | `**{dotted-circle}** No` | **{dotted-circle}** No |
+| Yes    | `**{check-circle}** Yes` | **{check-circle}** Yes |
 
 ## Quotes
 
@@ -890,8 +947,8 @@ search engine optimization (SEO), use the imperative, where possible.
 For guidelines on capitalizing headings, see the section on [capitalization](#capitalization).
 
 NOTE: **Note:**
-If you change an existing title, be careful. Any such changes may affect not
-only [links](#anchor-links) within the page, but may also affect links to the
+If you change an existing title, be careful. These changes might affect not
+only [links](#anchor-links) within the page, but might also affect links to the
 GitLab documentation from both the GitLab application and external sites.
 
 ### Anchor links
@@ -1095,14 +1152,26 @@ document to ensure it links to the most recent version of the file.
 
 ## Navigation
 
-To indicate the steps of navigation through the user interface:
+When documenting navigation through the user interface:
 
-- Use the exact word as shown in the UI, including any capital letters as-is.
+- Use the exact wording as shown in the UI, including any capital letters as-is.
 - Use bold text for navigation items and the char "greater than" (`>`) as a
-  separator (for example, `Navigate to your project's **Settings > CI/CD**` ).
+  separator. For example: `Navigate to your project's **Settings > CI/CD**`.
 - If there are any expandable menus, make sure to mention that the user needs to
-  expand the tab to find the settings you're referring to (for example,
-  `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
+  expand the tab to find the settings you're referring to. For example:
+  `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`.
+
+### Navigational elements
+
+Use the following terms when referring to the main GitLab user interface
+elements:
+
+- **Top menu**: This is the top menu that spans the width of the user interface.
+  It includes the GitLab logo, search field, counters, and the user's avatar.
+- **Left sidebar**: This is the navigation sidebar on the left of the user
+  interface, specific to the project or group.
+- **Right sidebar**: This is the navigation sidebar on the right of the user
+  interface, specific to the open issue, merge request, or epic.
 
 ## Images
 
@@ -1162,9 +1231,6 @@ that:
 - Are accurate, succinct, and unique.
 - Don't use *image of …* or *graphic of…* to describe the image.
 
-Also, if a heading immediately follows an image, be sure to add three dashes
-(`---`) between the image and the heading.
-
 ### Remove image shadow
 
 All images displayed on the [GitLab documentation site](https://docs.gitlab.com)
@@ -1249,7 +1315,7 @@ reviewed and approved by a technical writer.
 1. In YouTube, visit the video URL you want to display. Copy the regular URL
    from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace
    the video title and link in the line under `<div class="video-fallback">`.
-1. In YouTube, click **Share**, and then click **Embed**.
+1. In YouTube, select **Share**, and then select **Embed**.
 1. Copy the `<iframe>` source (`src`) **URL only**
    (`https://www.youtube.com/embed/VIDEO-ID`),
    and paste it, replacing the content of the `src` field in the
@@ -1292,6 +1358,9 @@ the documentation site, but will be displayed on GitLab's `/help`.
   added to code blocks. To make things easier for the user, always add a full
   code block for things that can be useful to copy and paste, as they can easily
   do it with the button on code blocks.
+- HTTP methods (`HTTP POST`) and HTTP status codes, both full (`404 File Not Found`)
+  and abbreviated (`404`), should be wrapped in inline code blocks when used in sentences.
+  For example: Send a `DELETE` request to delete the runner. Send a `POST` request to create one.
 - Add a blank line above and below code blocks.
 - When providing a shell command and its output, prefix the shell command with `$`
   and leave a blank line between the command and the output.
@@ -1416,17 +1485,17 @@ interface:
 Use an icon when you find yourself having to describe an interface element. For
 example:
 
-- Do: Click the Admin Area icon ( **{admin}** ).
-- Don't: Click the Admin Area icon (the wrench icon).
+- Do: Select the Admin Area icon ( **{admin}** ).
+- Don't: Select the Admin Area icon (the wrench icon).
 
 ## Alert boxes
 
 When you need to call special attention to particular sentences, use the
 following markup to create highlighted alert boxes.
 
-Note that the alert boxes only work for one paragraph only. Multiple paragraphs,
-lists, headers and so on, will not render correctly. For multiple lines, use
-[blockquotes](#blockquotes) instead.
+Alert boxes work for one paragraph only. Multiple paragraphs, lists, and headers
+won't render correctly. For multiple lines, use [blockquotes](#blockquotes)
+instead.
 
 Alert boxes render only on the GitLab documentation site (<https://docs.gitlab.com>).
 Within GitLab itself, they will appear as plain Markdown text (like the examples
@@ -1444,23 +1513,20 @@ guidelines, but for consistency you should try to use these values:
 
 ### Note
 
-Notes catch the eye of most readers, and therefore should be used very sparingly.
-In most cases, content considered for a note should be included:
+Notes indicate additional information that is of special use to the reader.
+Notes are most effective when used _sparingly_.
 
-- As just another sentence in the previous paragraph or the most-relevant
-  paragraph.
-- As its own standalone paragraph.
-- As content under a new subheading that introduces the topic, making it more
-  visible or findable.
+Try to avoid them. Too many notes can impact the scannability of a topic and
+create an overly busy page.
 
-#### When to use
+Instead of adding a note, try one of these alternatives:
 
-Use a note when there is a reason that most or all readers who browse the
-section should see the content. That is, if missed, it’s likely to cause major
-trouble for a minority of users or significant trouble for a majority of users.
+- Re-write the sentence as part of the most-relevant paragraph.
+- Put the information into its own standalone paragraph.
+- Put the content under a new subheading that introduces the topic, which makes
+  it more visible.
 
-Weigh the costs of distracting users to whom the content is not relevant against
-the cost of users missing the content if it were not expressed as a note.
+If you must use a note, use the following formatting:
 
 ```markdown
 NOTE: **Note:**
@@ -1582,12 +1648,11 @@ application:
 The following are recommended verbs for specific uses with user interface
 elements:
 
-| Recommended         | Used for                   | Replaces                   |
-|:--------------------|:---------------------------|:---------------------------|
-| *click*             | buttons, links, menu items | "hit", "press", "select"   |
-| *select* or *clear* | checkboxes                 | "enable", "click", "press" |
-| *select*            | dropdowns                  | "pick"                     |
-| *expand*            | expandable sections        | "open"                     |
+| Recommended         | Used for                              | Replaces                   |
+|:--------------------|:--------------------------------------|:---------------------------|
+| *select*            | buttons, links, menu items, dropdowns | "click, "press," "hit"     |
+| *select* or *clear* | checkboxes                            | "enable", "click", "press" |
+| *expand*            | expandable sections                   | "open"                     |
 
 ### Other Verbs
 
@@ -1614,6 +1679,15 @@ heading level.
 
 ### Text for documentation requiring version text
 
+When a feature is new or updated, you can add version information as a bulleted
+item in the **Version history**, or as an inline reference with related text.
+
+#### Version text in the **Version History**
+
+If all content in a section is related, add version text in a bulleted list
+following the heading for the section. To render correctly, it must be on its
+own line and surrounded by blank lines.
+
 - For features that need to declare the GitLab version that the feature was
   introduced. Text similar to the following should be added immediately below
   the heading as a blockquote:
@@ -1663,9 +1737,20 @@ heading level.
    and replaced by [Feature name](link-to-feature-documentation).
    ```
 
-NOTE: **Note:**
-Version text must be on its own line and surrounded by blank lines to render
-correctly.
+#### Inline version text
+
+If you're adding content to an existing topic, you can add version information
+inline with the existing text.
+
+In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`.
+If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4)`
+
+Including the issue link is encouraged, but isn't a requirement. For example:
+
+```markdown
+The voting strategy (introduced in GitLab 13.4) requires
+the primary and secondary voters to agree.
+```
 
 ### Versions in the past or future
 
@@ -1807,7 +1892,7 @@ for the changes to take effect.
 
 If the document you are editing resides in a place other than the GitLab CE/EE
 `doc/` directory, instead of the relative link, use the full path:
-`https://docs.gitlab.com/ce/administration/restart_gitlab.html`. Replace
+`https://docs.gitlab.com/ee/administration/restart_gitlab.html`. Replace
 `reconfigure` with `restart` where appropriate.
 
 ### Installation guide
@@ -1894,216 +1979,9 @@ steps aren't required, consider setting up a [table](#tables) with headers of
 Learn how to [document features deployed behind flags](feature_flags.md). For
 guidance on developing GitLab with feature flags, see [Feature flags in development of GitLab](../feature_flags/index.md).
 
-## RESTful API
-
-REST API resources are documented in Markdown under
-[`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each
-resource has its own Markdown file, which is linked from `api_resources.md`.
-
-When modifying the Markdown, also update the corresponding
-[OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi)
-if one exists for the resource. If not, consider creating one. Match the latest
-[OpenAPI 3.0.x specification](https://swagger.io/specification/). (For more
-information, see the discussion in this
-[issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16023#note_370901810).)
-
-In the Markdown doc for a resource (AKA endpoint):
-
-- Every method must have the REST API request. For example:
-
-  ```plaintext
-  GET /projects/:id/repository/branches
-  ```
-
-- Every method must have a detailed [description of the parameters](#method-description).
-- Every method must have a cURL example.
-- Every method must have a response body (in JSON format).
-
-### API topic template
-
-The following can be used as a template to get started:
-
-````markdown
-## Descriptive title
-
-One or two sentence description of what endpoint does.
-
-```plaintext
-METHOD /endpoint
-```
-
-| Attribute   | Type     | Required | Description           |
-|:------------|:---------|:---------|:----------------------|
-| `attribute` | datatype | yes/no   | Detailed description. |
-| `attribute` | datatype | yes/no   | Detailed description. |
-
-Example request:
-
-```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/endpoint?parameters"
-```
-
-Example response:
-
-```json
-[
-  {
-  }
-]
-```
-````
-
-### Fake user information
-
-You may need to demonstrate an API call or a cURL command that includes the name
-and email address of a user. Don't use real user information in API calls:
-
-- **Email addresses**: Use an email address ending in `example.com`.
-- **Names**: Use strings like `Example Username`. Alternatively, use diverse or
-  non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`,
-  or `Maria Garcia`.
-
-### Fake URLs
-
-When including sample URLs in the documentation, use:
-
-- `example.com` when the domain name is generic.
-- `gitlab.example.com` when referring to self-managed instances of GitLab.
-
-### Fake tokens
-
-There may be times where a token is needed to demonstrate an API call using
-cURL or a variable used in CI. It is strongly advised not to use real tokens in
-documentation even if the probability of a token being exploited is low.
-
-You can use the following fake tokens as examples:
-
-| Token type            | Token value                                                        |
-|:----------------------|:-------------------------------------------------------------------|
-| Private user token    | `<your_access_token>`                                              |
-| Personal access token | `n671WNGecHugsdEDPsyo`                                             |
-| Application ID        | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
-| Application secret    | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` |
-| CI/CD variable        | `Li8j-mLUVA3eZYjPfd_H`                                             |
-| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd`                                         |
-| Shared runner token   | `6Vk7ZsosqQyfreAxXTZr`                                             |
-| Trigger token         | `be20d8dcc028677c931e04f3871a9b`                                   |
-| Webhook secret token  | `6XhDroRcYPM5by_h-HLY`                                             |
-| Health check token    | `Tu7BgjR9qeZTEyRzGG2P`                                             |
-| Request profile token | `7VgpS4Ax5utVD2esNstz`                                             |
-
-### Method description
-
-Use the following table headers to describe the methods. Attributes should
-always be in code blocks using backticks (`` ` ``).
-
-```markdown
-| Attribute | Type | Required | Description |
-|:----------|:-----|:---------|:------------|
-```
-
-Rendered example:
-
-| Attribute | Type   | Required | Description         |
-|:----------|:-------|:---------|:--------------------|
-| `user`    | string | yes      | The GitLab username |
-
-### cURL commands
-
-- Use `https://gitlab.example.com/api/v4/` as an endpoint.
-- Wherever needed use this personal access token: `<your_access_token>`.
-- Always put the request first. `GET` is the default so you don't have to
-  include it.
-- Wrap the URL in double quotes (`"`).
-- Prefer to use examples using the personal access token and don't pass data of
-  username and password.
-
-| Methods                                         | Description                                           |
-|:-------------------------------------------     |:------------------------------------------------------|
-| `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed |
-| `--request POST`                                | Use this method when creating new objects             |
-| `--request PUT`                                 | Use this method when updating existing objects        |
-| `--request DELETE`                              | Use this method when removing existing objects        |
-
-### cURL Examples
-
-The following sections include a set of [cURL](https://curl.haxx.se) examples
-you can use in the API documentation.
-
-#### Simple cURL command
-
-Get the details of a group:
-
-```shell
-curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/gitlab-org"
-```
-
-#### cURL example with parameters passed in the URL
-
-Create a new project under the authenticated user's namespace:
-
-```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?name=foo"
-```
-
-#### Post data using cURL's `--data`
-
-Instead of using `--request POST` and appending the parameters to the URI, you
-can use cURL's `--data` option. The example below will create a new project
-`foo` under the authenticated user's namespace.
-
-```shell
-curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
-```
-
-#### Post data using JSON content
-
-NOTE: **Note:**
-In this example we create a new group. Watch carefully the single and double
-quotes.
-
-```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups"
-```
-
-#### Post data using form-data
-
-Instead of using JSON or urlencode you can use multipart/form-data which
-properly handles data encoding:
-
-```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "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.
-
-#### 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
-contains spaces in its title. Observe how spaces are escaped using the `%20`
-ASCII code.
-
-```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"
-```
-
-Use `%2F` for slashes (`/`).
-
-#### Pass arrays to API calls
-
-The GitLab API sometimes accepts arrays of strings or integers. For example, to
-exclude specific users when requesting a list of users for a project, you would
-do something like this:
-
-```shell
-curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "skip_users[]=<user_id>" --data "skip_users[]=<user_id>" "https://gitlab.example.com/api/v4/projects/<project_id>/users"
-```
-
 ## GraphQL API
 
-GraphQL APIs are different from [RESTful APIs](#restful-api). Reference
+GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference
 information is generated in our [GraphQL reference](../../api/graphql/reference/index.md).
 
 However, it's helpful to include examples on how to use GraphQL for different
@@ -2158,7 +2036,7 @@ Set up the section with the following:
   ```markdown
   1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`.
   1. Paste the `query` listed above into the left window of your GraphiQL explorer tool.
-  1. Click Play to get the result shown here:
+  1. Select Play to get the result shown here:
   ```
 
 - Include a screenshot of the result in the GraphiQL explorer. Follow the naming