Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42

5 files changed, 39 insertions, 22 deletions

diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md
index 7dd02c44afa..7fa80e2d0f5 100644
--- a/doc/development/documentation/feature_flags.md
+++ b/doc/development/documentation/feature_flags.md
@@ -52,7 +52,7 @@ Include details of the feature flag in the documentation:
   [by-project information](#features-enabled-by-project). Otherwise,
   do not say anything about it.
 - Say whether it's recommended for production use.
-- Document how to enable and disable it.
+- Document how to enable and disable it, preferably at the end of the file.
 - 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
@@ -110,7 +110,7 @@ default:
   [by-project information](#features-enabled-by-project). Otherwise,
   do not say anything about it.
 - Say whether it's recommended for production use.
-- Document how to disable and enable it.
+- Document how to disable and enable it, preferably at the end of the file.
 - Add a warning to the user saying that the feature might be disabled.
 
 For example, for a feature initially deployed disabled by default, that became
@@ -169,7 +169,7 @@ For features enabled by default:
   [by-project information](#features-enabled-by-project). Otherwise,
   do not say anything about it.
 - Say whether it's recommended for production use.
-- Document how to disable and enable it.
+- Document how to disable and enable it, preferably at the end of the file.
 - Add a warning to the user saying that the feature might be disabled.
 
 For example, for a feature enabled by default, enabled on GitLab.com, that
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index f10396570a2..05aa003d89e 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -411,7 +411,7 @@ on how the left-side navigation menu is built and updated.
 
 NOTE:
 To preview your changes to documentation locally, follow this
-[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
+[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md).
 
 The live preview is currently enabled for the following projects:
 
@@ -502,7 +502,7 @@ help of a configuration file known as **screenshot generator**.
 
 To run the tool on an existing screenshot generator, take the following steps:
 
-1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
+1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md).
 1. Navigate to the subdirectory with your cloned GitLab repository, typically `gdk/gitlab`.
 1. Make sure that your GDK database is fully migrated: `bin/rake db:migrate RAILS_ENV=development`.
 1. Install `pngquant`, see the tool website for more information: [`pngquant`](https://pngquant.org/)
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index 33bfc040bb6..67bdbffa2a1 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -58,6 +58,9 @@ Don't tell them **how** to do this thing. Tell them **what it is**.
 
 If you start describing another topic, start a new concept and link to it.
 
+Also, do not use "Overview" or "Introduction" for the topic title. Instead,
+use a noun or phrase that someone would search for.
+
 Concept topics should be in this format:
 
 ```markdown
@@ -111,13 +114,16 @@ Prerequisites:
 To create an issue:
 
 1. Go to **Issues > List**.
-1. In the top right, click **New issue**.
+1. In the top right, select **New issue**.
 1. Complete the fields. (If you have a reference topic that lists each field, link to it here.)
-1. Click **Create issue**.
+1. Select **Create issue**.
 
 The issue is created. You can view it by going to **Issues > List**.
 ```
 
+If you have several tasks on a page that share prerequisites, you can make a
+reference topic with the title **Prerequisites**, and link to it.
+
 ## Reference
 
 A reference topic provides information in an easily-scannable format,
@@ -133,6 +139,9 @@ Introductory sentence.
 | **Name** | Descriptive sentence about the setting. |
 ```
 
+If a feature or concept has its own prerequisites, you can use the reference
+topic type to create a **Prerequisites** header for the information.
+
 ## Troubleshooting
 
 Troubleshooting topics can be one of two categories:
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 25cdbaf75ba..0ac393a8509 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -164,13 +164,12 @@ standard for GitLab documentation).
 
 A rule that could cause confusion is `MD044/proper-names`, as it might not be
 immediately clear what caused markdownlint to fail, or how to correct the
-failure. This rule checks a list of known words, listed in the `.markdownlint.json`
+failure. This rule checks a list of known words, listed in the `.markdownlint.yml`
 file in each project, to verify proper use of capitalization and backticks.
 Words in backticks are ignored by markdownlint.
 
 In general, product names should follow the exact capitalization of the official
-names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json)
-for the words tested for proper capitalization in GitLab documentation.
+names of the products, protocols, and so on.
 
 Some examples fail if incorrect capitalization is used:
 
@@ -370,7 +369,7 @@ Capitalize names of:
 - Third-party organizations, software, and products. For example, Prometheus,
   Kubernetes, Git, and The Linux Foundation.
 - Methods or methodologies. For example, Continuous Integration,
-  Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).)
+  Continuous Deployment, Scrum, and Agile.
 
 Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation)
 for the entity, which may use non-standard case styles. For example: GitLab and
@@ -1112,13 +1111,9 @@ document to ensure it links to the most recent version of the file.
 When documenting navigation through the user interface:
 
 - 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: `From your project, go to **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:
-  `From your group, go to **Settings > CI/CD** and expand **General pipelines**`.
+- Use bold text for navigation items.
 
-### Navigational elements
+### What to call the menus
 
 Use these terms when referring to the main GitLab user interface
 elements:
@@ -1130,6 +1125,19 @@ elements:
 - **Right sidebar**: This is the navigation sidebar on the right of the user
   interface, specific to the open issue, merge request, or epic.
 
+### How to document the left sidebar
+
+To be consistent, use this format when you refer to the left sidebar.
+
+- Go to your project and select **Settings > CI/CD**.
+- Go to your group and select **Settings > CI/CD**.
+- Go to the Admin Area (**{admin}**) and select **Overview > Projects**.
+
+For expandable menus, use this format:
+
+1. Go to your group and select **Settings > CI/CD**.
+1. Expand **General pipelines**.
+
 ## Images
 
 Images, including screenshots, can help a reader better understand a concept.
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index aee3144e6de..af95f3b9023 100644
--- a/doc/development/documentation/testing.md
+++ b/doc/development/documentation/testing.md
@@ -150,11 +150,11 @@ from those guidelines.
 
 markdownlint configuration is found in the following projects:
 
-- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json)
-- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json)
-- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json)
-- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json)
-- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json)
+- [`gitlab`](https://gitlab.com/gitlab-org/gitlab)
+- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner)
+- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab)
+- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab)
+- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit)
 
 This configuration is also used in build pipelines.