Merge branch 'mjang-imperative-over-gerund' into 'master'

Docs: Include guidance on header titles

Closes gitlab-docs#630

See merge request gitlab-org/gitlab!24094

doc/development/documentation/styleguide.md

@@ -175,7 +175,7 @@ The table below shows what kind of documentation goes where.
 | `doc/update/`         | Contains instructions for updating GitLab. |
 | `doc/topics/`         | Indexes per topic (`doc/topics/topic-name/index.md`): all resources for that topic. |
 
-### Working with directories and files
+### Work with directories and files
 
 1. When you create a new directory, always start with an `index.md` file.
    Do not use another file name and **do not** create `README.md` files.
@@ -530,6 +530,16 @@ For other punctuation rules, please refer to the
   document. For example, `## Examples` is a bad heading; `## GitLab Pages examples`
   is a better one. It's not an exact science, but please consider this carefully.
 
+### Heading titles
+
+Keep heading titles clear and direct. Make every word count. To accommodate search engine optimization (SEO), use the imperative, where possible.
+
+| Do   | Don't   |
+|:-----|:--------|
+| Configure GDK | Configuring GDK |
+| GitLab Release and Maintenance Policy | This section covers GitLab's Release and Maintenance Policy |
+| Backport to older releases | Backporting to older releases |
+
 ### Anchor links
 
 Headings generate anchor links automatically when rendered. `## This is an example`
@@ -828,7 +838,7 @@ Usage examples:
   [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/):
   `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}**
 
-### Using GitLab SVGs to describe UI elements
+### Use GitLab SVGs to describe UI elements
 
 When using GitLab SVGs to describe screen elements, also include the name or tooltip of the element as text.
 
@@ -1003,7 +1013,7 @@ Examples:
 - "Open a merge request to fix a broken link".
 - "After you open a merge request (MR), submit your MR for review and approval".
 
-### Describing UI elements
+### Describe UI elements
 
 The following are styles to follow when describing UI elements on a screen:
 

doc/development/documentation/workflow.md

@@ -382,7 +382,7 @@ Ensure the following if skipping an initial Technical Writer review:
 - Specific [user permissions](../../user/permissions.md) are documented.
 - That new documents are linked from higher-level indexes, for discoverability.
 - Style guide is followed:
-  - For [directories and files](styleguide.md#working-with-directories-and-files).
+  - For [directories and files](styleguide.md#work-with-directories-and-files).
   - For [images](styleguide.md#images).
 
 NOTE: **Note:**

scripts/lint-doc.sh

@@ -43,7 +43,7 @@ if [ ${FIND_READMES} -ne $NUMBER_READMES ]
 then
   echo
   echo '  ✖ ERROR: New README.md file(s) detected, prefer index.md over README.md.' >&2
-  echo '  https://docs.gitlab.com/ee/development/documentation/styleguide.html#working-with-directories-and-files'
+  echo '  https://docs.gitlab.com/ee/development/documentation/styleguide.html#work-with-directories-and-files'
   echo
   exit 1
 fi