summaryrefslogtreecommitdiff
path: root/doc/development/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/documentation')
-rw-r--r--doc/development/documentation/index.md19
-rw-r--r--doc/development/documentation/site_architecture/global_nav.md37
-rw-r--r--doc/development/documentation/site_architecture/index.md4
-rw-r--r--doc/development/documentation/structure.md204
-rw-r--r--doc/development/documentation/styleguide/index.md144
-rw-r--r--doc/development/documentation/styleguide/word_list.md170
-rw-r--r--doc/development/documentation/testing.md14
-rw-r--r--doc/development/documentation/workflow.md2
8 files changed, 382 insertions, 212 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index 12a1912dd25..91215ca21b4 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -115,15 +115,15 @@ each page should have a metadata tag called `type`. It can be one or more of the
following:
- `index`: It consists mostly of a list of links to other pages.
- [Example page](../../README.md).
+ [Example page](../../index.md).
- `concepts`: The background or context of a subject.
[Example page](../../topics/autodevops/index.md).
- `howto`: Specific use case instructions.
- [Example page](../../ssh/README.md).
+ [Example page](../../ssh/index.md).
- `tutorial`: Learn a process/concept by doing.
[Example page](../../gitlab-basics/start-using-git.md).
- `reference`: A collection of information used as a reference to use a feature
- or a functionality. [Example page](../../ci/yaml/README.md).
+ or a functionality. [Example page](../../ci/yaml/index.md).
### Redirection metadata
@@ -395,7 +395,7 @@ This is preferred over static paths, as the helper also works on instances insta
### GitLab `/help` tests
Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/features/help_pages_spec.rb)
-are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`.
+are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../index.md) works correctly from `/help`.
For example, [GitLab.com's `/help`](https://gitlab.com/help).
## Docs site architecture
@@ -475,12 +475,12 @@ 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_pipelines.md)
+- [Manual actions](../../ci/yaml/index.md#whenmanual)
+- [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md)
- [Review Apps](../../ci/review_apps/index.md)
-- [Artifacts](../../ci/yaml/README.md#artifacts)
+- [Artifacts](../../ci/yaml/index.md#artifacts)
- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects)
-- [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md)
+- [Pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md)
## Testing
@@ -556,6 +556,3 @@ padding. The padding is added around the element, enlarging the screenshot area.
#### Live example
Please use `spec/docs_screenshots/container_registry_docs.rb` as a guide and as an example to create your own scripts.
-
-<!-- This redirect file can be deleted after February 1, 2021. -->
-<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md
index aeaf12e23d1..3845586ce60 100644
--- a/doc/development/documentation/site_architecture/global_nav.md
+++ b/doc/development/documentation/site_architecture/global_nav.md
@@ -12,21 +12,40 @@ description: "Learn how GitLab docs' global navigation works and how to add new
> - [Per-project](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/498) navigation added in GitLab 12.2.
> - [Unified global navigation](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/1482) added in GitLab 13.11.
-Global navigation (the left-most pane in our three pane documentation) provides:
+Global navigation is the left-most pane in the documentation. You can use the
+"global nav" to browse the content.
-- A high-level grouped view of product features.
-- The ability to discover new features by browsing the menu structure.
-- A way to allow the reader to focus on product areas.
-- The ability to refine landing pages, so they don't have to do all the work of surfacing
- every page contained within the documentation.
+Research shows that people use Google to search for GitLab product documentation. When they land on a result,
+we want them to find topics nearby that are related to the content they're reading. The global nav provides this information.
-## Adding new items
+At the highest level, our global nav is workflow-based. Navigation needs to help users build a mental model of how to use GitLab.
+The levels under each of the higher workflow-based topics are the names of features.
+For example:
+
+**Use GitLab** (_workflow_) **> Build your application** (_workflow_) **> CI/CD** (_feature_) **> Pipelines** (_feature)
+
+## Choose the right words for your navigation entry
+
+Before you add an item to the left nav, choose the parts of speech you want to use.
+
+The nav entry should match the page title. However, if the title is too long,
+when you shorten the phrase, use either:
+
+- A noun, like **Merge requests**.
+- An active verb, like **Install GitLab** or **Get started with runners**.
+
+Use a phrase that clearly indicates what the page is for. For example, **Get started** is not
+as helpful as **Get started with runners**.
+
+## Add a navigation entry
+
+All topics should be included in the left nav.
To add a topic to the global nav, edit
[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml)
and add your item.
-All new pages need a new navigation item. Without a navigation, the page becomes "orphaned". That
+All new pages need a navigation item. Without a navigation, the page becomes "orphaned." That
is:
- The navigation shuts when the page is opened, and the reader loses their place.
@@ -93,7 +112,7 @@ for clarity.
To see the improvements planned, check the
[global nav epic](https://gitlab.com/groups/gitlab-org/-/epics/1599).
-**Do not** [add items](#adding-new-items) to the global nav without
+**Do not** [add items](#add-a-navigation-entry) to the global nav without
the consent of one of the technical writers.
## Composition
diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md
index d410d77a1a0..a1e08a9c19b 100644
--- a/doc/development/documentation/site_architecture/index.md
+++ b/doc/development/documentation/site_architecture/index.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
The [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project hosts
the repository which is used to generate the GitLab documentation website and
-is deployed to <https://docs.gitlab.com>. It uses the [Nanoc](https://nanoc.ws/)
+is deployed to <https://docs.gitlab.com>. It uses the [Nanoc](https://nanoc.app/)
static site generator.
## Architecture
@@ -146,7 +146,7 @@ Read more about the [deployment process](deployment_process.md).
The easiest way to achieve something similar to
[Jekyll's data files](https://jekyllrb.com/docs/datafiles/) in Nanoc is by
-using the [`@items`](https://nanoc.ws/doc/reference/variables/#items-and-layouts)
+using the [`@items`](https://nanoc.app/doc/reference/variables/#items-and-layouts)
variable.
The data file must be placed inside the `content/` directory and then it can
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index 871fb26ce08..ac934673ee2 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -7,61 +7,40 @@ description: What to include in GitLab documentation pages.
# Documentation topic types
-At GitLab, we have not traditionally used topic types. However, we are starting to
-move in this direction, and we now use four topic types:
+At GitLab, we have not traditionally used types for our content. However, we are starting to
+move in this direction, and we now use four primary topic types:
- [Concept](#concept)
- [Task](#task)
- [Reference](#reference)
- [Troubleshooting](#troubleshooting)
-Each page contains multiple topic types. For example,
-a page with the title `Pipelines`, which is generated from a file called `index.md`,
-can include a concept and multiple task and reference topics.
+In general, each page in our docset contains multiple topics. (Each heading indicates a new topic.)
+Each topic on a page should be a specific topic type. For example,
+a page with the title `Pipelines` can include topics that are concepts and tasks.
-GitLab also uses high-level landing pages.
-
-## Landing pages
-
-Landing pages are topics that group other topics and help a user to navigate a section.
-
-Users who are using the in-product help do not have a left nav,
-and need these topics to navigate the documentation.
-
-These topics can also help other users find the most important topics
-in a section.
-
-Landing page topics should be in this format:
-
-```markdown
-# Title (a noun, like "CI/CD or "Analytics")
-
-Brief introduction to the concept or product area.
-Include the reason why someone would use this thing.
-
-- Bulleted list of important related topics.
-- These links are needed because users of in-product help do not have left navigation.
-```
+A page might also contain only one type of information. These pages are generally one of our
+[other content types](#other-types-of-content).
## Concept
-A concept topic introduces a single feature or concept.
+A concept introduces a single feature or concept.
A concept should answer the questions:
- What is this?
- Why would I use it?
-Think of everything someone might want to know if they've never heard of this topic before.
+Think of everything someone might want to know if they've never heard of this concept before.
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.
+If you start describing another concept, start a new concept and link to it.
-Also, do not use "Overview" or "Introduction" for the topic title. Instead,
+Also, do not use **Overview** or **Introduction** for the title. Instead,
use a noun or phrase that someone would search for.
-Concept topics should be in this format:
+Concepts should be in this format:
```markdown
# Title (a noun, like "Widgets")
@@ -71,14 +50,14 @@ A paragraph that explains what this thing is.
Another paragraph that explains what this thing is.
Remember, if you start to describe about another concept, stop yourself.
-Each concept topic should be about one concept only.
+Each concept should be about one concept only.
```
## Task
-A task topic gives instructions for how to complete a procedure.
+A task gives instructions for how to complete a procedure.
-Task topics should be in this format:
+Tasks should be in this format:
```markdown
# Title (starts with an active verb, like "Create a widget" or "Delete a widget")
@@ -113,20 +92,21 @@ Prerequisites:
To create an issue:
-1. Go to **Issues > List**.
-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. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Issues > List**.
+1. In the top right corner, select **New issue**.
+1. Complete the fields. (If you have reference content that lists each field, link to it here.)
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.
+If you have several tasks on a page that share prerequisites, you can use the title
+**Prerequisites**, and link to it.
## Reference
-A reference topic provides information in an easily-scannable format,
+Reference information should be in an easily-scannable format,
like a table or list. It's similar to a dictionary or encyclopedia entry.
```markdown
@@ -139,18 +119,18 @@ 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.
+If a feature or concept has its own prerequisites, you can use reference
+content to create a **Prerequisites** header for the information.
## Troubleshooting
-Troubleshooting topics can be one of two categories:
+Troubleshooting can be one of two categories:
-- **Troubleshooting task.** This topic is written the same as a [standard task topic](#task).
+- **Troubleshooting task.** This information is written the same way as a [standard task](#task).
For example, "Run debug tools" or "Verify syntax."
-- **Troubleshooting reference.** This topic has a specific format.
+- **Troubleshooting reference.** This information has a specific format.
-Troubleshooting reference topics should be in this format:
+Troubleshooting reference information should be in this format:
```markdown
# Title (the error message or a description of it)
@@ -162,25 +142,125 @@ This issue occurs when...
The workaround is...
```
-For the topic title:
+For the heading:
-- Consider including at least a partial error message in the title.
+- Consider including at least a partial error message.
- Use fewer than 70 characters.
-Remember to include the complete error message in the topics content if it is
-not complete in the title.
+If you do not put the full error in the title, include it in the body text.
+
+## Other types of content
+
+There are other types of content in the GitLab documentation that don't
+classify as one of the four primary [topic types](#documentation-topic-types).
+These include:
+
+- [Tutorials](#tutorials)
+- [Get started pages](#get-started)
+- [Topics and resources pages](#topics-and-resources-pages)
+
+In most cases, these pages are standalone.
+
+### Tutorials
+
+A tutorial is an end-to-end walkthrough of a complex workflow or scenario.
+In general, you might consider using a tutorial when:
+
+- The workflow requires a number of sequential steps where each step consists
+ of sub-steps.
+- The steps cover a variety of GitLab features or third-party tools.
+
+Tutorials are learning aids that complement our core documentation.
+They do not introduce new features.
+Always use the primary [topic types](#documentation-topic-types) to document new features.
+
+Tutorials should be in this format:
+
+```markdown
+# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website")
+
+A paragraph that explains what the tutorial does, and the expected outcome.
+
+To create a website:
+
+- [Step 1: Do the first task](#do-the-first-task)
+- [Step 2: Do the second task](#do-the-second-task)
+
+Prerequisites (optional):
+
+- Thing 1
+- Thing 2
+- Thing 3
+
+## Do the first task
+
+To do step 1:
+
+1. First step.
+2. Another step.
+3. Another step.
+
+## Do the second task
+
+Before you begin, make sure you have [done the first task](#do-the-first-task).
+
+To do step 2:
+
+1. First step.
+2. Another step.
+3. Another step.
+```
+
+### Get started
+
+A get started page is a set of steps to help a user get set up
+quickly to use a single GitLab feature or tool.
+It might consist of more than one task.
+
+Get started pages should be in this format:
+
+```markdown
+# Title ("Get started with <feature>")
+
+Complete the following steps to ... .
+
+1. First step.
+1. Another step.
+1. Another step.
+
+If you need to add more than one task,
+consider using subsections for each distinct task.
+```
-## Other information on a topic
+### Topics and resources pages
-Topics include other information.
+This is a page with a list of links that point to important sections
+of documentation for a specific GitLab feature or tool.
-For example:
+We do not encourage the use of these types of pages.
+Lists like this can get out of date quickly and offer little value to users.
+We've included this type here because:
-- Each topic must have a [tier badge](styleguide/index.md#product-tier-badges).
-- New topics must have information about the
- [GitLab version where the feature was introduced](styleguide/index.md#where-to-put-version-text).
+- There are existing pages in the documentation that follow this format,
+ and they should be standardized.
+- They can sometimes help navigate a complex section of the documentation.
+
+If you come across a page like this
+or you have to create one, use this format:
+
+```markdown
+# Title ("Topics and resources for <feature>")
+
+Brief sentence to describe the feature.
+
+Refer to these resources for more information about <this feature>:
+
+- Link 1
+- Link 2
+- Link 3
+```
-### Help and feedback section
+## Help and feedback section
This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4)
is displayed at the end of each document and can be omitted by adding a key into
@@ -195,7 +275,7 @@ feedback: false
The default is to leave it there. If you want to omit it from a document, you
must check with a technical writer before doing so.
-#### Disqus
+### Disqus
We also have integrated the docs site with Disqus (introduced by
[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)),
@@ -210,7 +290,7 @@ comments: false
---
```
-We're hiding comments only in main index pages, such as [the main documentation index](../../README.md),
+We're hiding comments only in main index pages, such as [the main documentation index](../../index.md),
since its content is too broad to comment on. Before omitting Disqus, you must
check with a technical writer.
@@ -221,7 +301,7 @@ The click events in the feedback section are tracked with Google Tag Manager.
The conversions can be viewed on Google Analytics by navigating to
**Behavior > Events > Top events > docs**.
-### Guidelines for good practices
+## Guidelines for good practices
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation.
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 7787366dbf4..a5345f3b52d 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -193,7 +193,7 @@ included in backticks. For example:
We include concept and task topic types in the same larger topic.
-In general, we have one topic that's a [landing page](../structure.md#landing-pages).
+In general, we have one topic that's a landing page.
Below that topic in the left nav are individual topics. Each of these include a concept
and multiple related tasks, reference, and troubleshooting topics.
@@ -304,7 +304,6 @@ GitLab documentation should be clear and easy to understand. Avoid unnecessary w
- Be clear, concise, and stick to the goal of the topic.
- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).)
-- Use [inclusive language](#inclusive-language).
- Rewrite to avoid wordiness:
- there is
- there are
@@ -385,80 +384,6 @@ references to user interface elements. For example:
- To sign in to product X, enter your credentials, and then select **Log in**.
-### Inclusive language
-
-We strive to create documentation that's inclusive. This section includes
-guidance and examples for these 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
-examples that illustrate some best practices to follow.
-
-#### Avoid gender-specific wording
-
-When possible, use gender-neutral pronouns. For example, you can use a singular
-[they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as
-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.
-
-#### Avoid ableist language
-
-Avoid terms that are also used in negative stereotypes for different groups.
-
-<!-- vale gitlab.InclusionAbleism = NO -->
-
-| Use | Avoid |
-|------------------------|----------------------|
-| Check for completeness | Sanity check |
-| Uncertain outliers | Crazy outliers |
-| Slows the service | Cripples the service |
-| Placeholder variable | Dummy variable |
-| 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.
-
-#### Culturally sensitive language
-
-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 [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.
@@ -574,7 +499,7 @@ Follow these guidelines for punctuation:
| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- |
| Use serial commas (_Oxford commas_) before the final _and_ or _or_ in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | _You can create new issues, merge requests, and milestones._ |
| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ |
-| Always use lowercase after a colon. | Linked issues: a way to create a relationship between issues._ |
+| When a colon is part of a sentence, always use lowercase after the colon. | _Linked issues: a way to create a relationship between issues._ |
<!-- vale gitlab.Repetition = YES -->
@@ -812,6 +737,35 @@ page), use these phrases:
| No | `**{dotted-circle}** No` | **{dotted-circle}** No |
| Yes | `**{check-circle}** Yes` | **{check-circle}** Yes |
+### Footnotes
+
+To indicate a footnote, use the HTML tag `<sup>` with a number.
+Put the tag at the end of the sentence or term.
+
+For the footnotes below the table, use a bold number followed by a sentence.
+
+For example:
+
+```markdown
+| App name | Description |
+|:---------|:---------------------------------|
+| App A | Description text. <sup>1</sup> |
+| App B | Description text. <sup>2</sup> |
+
+1. This is the footnote.
+1. This is the other footnote.
+```
+
+This text renders this output:
+
+| App name | Description |
+|:---------|:---------------------------------|
+| App A | Description text. <sup>1</sup> |
+| App B | Description text. <sup>2</sup> |
+
+1. This is the footnote.
+1. This is the other footnote.
+
## Quotes
Valid for Markdown content only, not for front matter entries:
@@ -1093,21 +1047,23 @@ elements:
To be consistent, use this format when you write about UI navigation.
-1. On the top bar, select **Menu > Project** and find your project.
+1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **General pipelines**.
Another example:
-1. On the top bar, select **Menu > Group** and find your group.
+1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **General pipelines**.
An Admin Area example:
-`1. On the top bar, select **Menu >** **{admin}** **Admin**.`
+```markdown
+1. On the top bar, select **Menu >** **{admin}** **Admin**.
+```
-This text generates this HTML:
+This text renders this output:
1. On the top bar, select **Menu >** **{admin}** **Admin**.
@@ -1510,25 +1466,6 @@ It renders on the GitLab documentation site as:
To maintain consistency through GitLab documentation, use these styles and terms.
-### Merge requests (MRs)
-
-Merge requests allow you to exchange changes you made to source code and
-collaborate with other people on the same project.
-
-- Use lowercase _merge requests_ regardless of whether referring to the feature
- or individual merge requests.
-
-As noted in the GitLab [Writing Style Guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines),
-if you use the _MR_ acronym, expand it at least once per document page.
-Typically, the first use would be phrased as _merge request (MR)_ with subsequent
-instances being _MR_.
-
-Examples:
-
-- "We prefer GitLab merge requests".
-- "Open a merge request to fix a broken link".
-- "After you open a merge request (MR), submit your MR for review and approval".
-
### Describe UI elements
Follow these styles when you're describing user interface elements in an
@@ -1558,7 +1495,7 @@ elements:
## GitLab versions
-GitLab product documentation pages (not including [Contributor and Development](../../README.md)
+GitLab product documentation pages (not including [Contributor and Development](../../index.md)
pages in the `/development` directory) can include version information to help
users be aware of recent improvements or additions.
@@ -1594,7 +1531,8 @@ the section. The version information must:
- Be surrounded by blank lines.
- Start with `>`. If there are multiple bullets, each line must start with `> -`.
- The string must include these words in this order (capitalization doesn't matter):
- - `introduced`, `deprecated`, `moved`
+ - `introduced`, `deprecated`, `changed`, `moved`, `recommended` (as in the
+ [feature flag documentation](../feature_flags.md)), `removed`, or `renamed`
- `in` or `to`
- `GitLab`
- Whenever possible, include a link to the completed issue, merge request, or epic
@@ -1757,7 +1695,7 @@ badges and tooltips (`<span class="badge-trigger free">`).
| _Only_ GitLab Ultimate SaaS (no self-managed instances) | `**(ULTIMATE SAAS)**` |
Topics that mention the `gitlab.rb` file are referring to
-self-managed instances of GitLab. To prevent confusion, include the relevant `TIER ONLY`
+self-managed instances of GitLab. To prevent confusion, include the relevant `TIER SELF`
tier badge on the highest applicable heading level on
the page.
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index fd8766bbfb6..3fba9078bab 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -9,6 +9,11 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab
To help ensure consistency in the documentation, follow this guidance.
+For guidance not on this page, we defer to these style guides:
+
+- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/)
+- [Google Developer Documentation Style Guide](https://developers.google.com/style)
+
<!-- vale off -->
<!-- markdownlint-disable -->
@@ -22,7 +27,13 @@ Use **administration**, **administrator**, **administer**, or **Admin Area** ins
## allow, enable
-Try to avoid, unless you are talking about security-related features. For example, instead of "This feature allows you to create a pipeline," use "Use this feature to create a pipeline." This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows).
+Try to avoid, unless you are talking about security-related features. For example:
+
+- Avoid: This feature allows you to create a pipeline.
+- Use instead: Use this feature to create a pipeline.
+
+This phrasing is more active and is from the user perspective, rather than the person who implemented the feature.
+[View details in the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows).
## and/or
@@ -32,25 +43,49 @@ Instead of **and/or**, use or or rewrite the sentence to spell out both options.
Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead.
+## blacklist
+
+Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
+
## currently
Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml))
## Developer
-When writing about the Developer role, use a capital "D." Do not use the phrase, "if you are a developer"
-to mean someone who is assigned the Developer role. Instead, write it out. "If you are assigned the Developer role..."
+When writing about the Developer role:
-Do not use "Developer permissions." A user who is assigned the Developer role has a set of associated permissions.
+- Use a capital **D**.
+- Do not use the phrase, **if you are a developer** to mean someone who is assigned the Developer
+ role. Instead, write it out. For example, **if you are assigned the Developer role**.
+- To describe a situation where the Developer role is the minimum required:
+ - Avoid: **the Developer role or higher**
+ - Use instead: **at least the Developer role**
+
+Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions.
+
+## disable
+
+See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance.
+Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
## easily
-Do not use. If the user doesn't find the process to be these things, we lose their trust.
+Do not use. If the user doesn't find the process to be easy, we lose their trust.
## e.g.
Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml))
+## email
+
+Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**.
+
+## enable
+
+See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance.
+Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
+
## future tense
When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml))
@@ -59,16 +94,35 @@ When possible, use present tense instead. For example, use `after you execute th
Do not make possessive (GitLab's). This guidance follows [GitLab Brand Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/brand-guidelines/#trademark).
+### GitLab.com
+
+Refers to the GitLab instance managed by GitLab itself.
+
+### GitLab SaaS
+
+Refers to the product license that provides access to GitLab.com. Does not refer to the
+GitLab instance managed by GitLab itself.
+
+### GitLab self-managed
+
+Refers to the product license for GitLab instances managed by customers themselves.
+
## Guest
-When writing about the Guest role, use a capital "G." Do not use the phrase, "if you are a guest"
-to mean someone who is assigned the Guest role. Instead, write it out. "If you are assigned the Guest role..."
+When writing about the Guest role:
+
+- Use a capital **G**.
+- Do not use the phrase, **if you are a guest** to mean someone who is assigned the Guest
+ role. Instead, write it out. For example, **if you are assigned the Guest role**.
+- To describe a situation where the Guest role is the minimum required:
+ - Avoid: **the Guest role or higher**
+ - Use instead: **at least the Guest role**
-Do not use "Guest permissions." A user who is assigned the Guest role has a set of associated permissions.
+Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions.
## handy
-Do not use. If the user doesn't find the process to be these things, we lose their trust.
+Do not use. If the user doesn't find the feature or process to be handy, we lose their trust.
## high availability, HA
@@ -84,10 +138,28 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v
## Maintainer
-When writing about the Maintainer role, use a capital "M." Do not use the phrase, "if you are a maintainer"
-to mean someone who is assigned the Maintainer role. Instead, write it out. "If you are assigned the Maintainer role..."
+When writing about the Maintainer role:
+
+- Use a capital **M**.
+- Do not use the phrase, **if you are a maintainer** to mean someone who is assigned the Maintainer
+ role. Instead, write it out. For example, **if you are assigned the Maintainer role**.
+- To describe a situation where the Maintainer role is the minimum required:
+ - Avoid: **the Maintainer role or higher**
+ - Use instead: **at least the Maintainer role**
+
+Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions.
+
+## mankind
+
+Do not use. Use **people** or **humanity** instead. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml))
-Do not use "Maintainer permissions." A user who is assigned the Maintainer role has a set of associated permissions.
+## manpower
+
+Do not use. Use words like **workforce** or **GitLab team members**. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml))
+
+## master
+
+Do not use. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
## may, might
@@ -97,12 +169,19 @@ Do not use "Maintainer permissions." A user who is assigned the Maintainer role
Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml))
+## merge requests
+
+Lowercase. If you use **MR** as the acronym, spell it out on first use.
+
## Owner
-When writing about the Owner role, use a capital "M." Do not use the phrase, "if you are an owner"
-to mean someone who is assigned the Owner role. Instead, write it out. "If you are assigned the Owner role..."
+When writing about the Owner role:
+
+- Use a capital **O**.
+- Do not use the phrase, **if you are an owner** to mean someone who is assigned the Owner
+ role. Instead, write it out. For example, **if you are assigned the Owner role**.
-Do not use "Owner permissions." A user who is assigned the Owner role has a set of associated permissions.
+Do not use **Owner permissions**. A user who is assigned the Owner role has a set of associated permissions.
## permissions
@@ -118,38 +197,68 @@ Do not use. Doing so may negatively affect other users and contributors, which i
## Reporter
-When writing about the Reporter role, use a capital "R." Do not use the phrase, "if you are a reporter"
-to mean someone who is assigned the Reporter role. Instead, write it out. "If you are assigned the Reporter role..."
+When writing about the Reporter role:
-Do not use "Reporter permissions." A user who is assigned the Reporter role has a set of associated permissions.
+- Use a capital **R**.
+- Do not use the phrase, **if you are a reporter** to mean someone who is assigned the Reporter
+ role. Instead, write it out. For example, **if you are assigned the Reporter role**.
+- To describe a situation where the Reporter role is the minimum required:
+ - Avoid: **the Reporter role or higher**
+ - Use instead: **at least the Reporter role**
+
+Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions.
## roles
Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions.
+## sanity check
+
+Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
+
## scalability
Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page.
-## simply
+## setup, set up
+
+Use **setup** as a noun, and **set up** as a verb. For example:
+
+- Your remote office setup is amazing.
+- To set up your remote office correctly, consider the ergonomics of your work area.
+
+## simply, simple
-Do not use. If the user doesn't find the process to be these things, we lose their trust.
+Do not use. If the user doesn't find the process to be simple, we lose their trust.
## slashes
-Instead of **and/or**, use **or** or another sensible construction. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed.
+Instead of **and/or**, use **or** or re-write the sentence. This rule also applies to other slashes, like **follow/unfollow**. Some exceptions (like **CI/CD**) are allowed.
+
+## slave
+
+Do not use. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
## subgroup
-Use instead of `sub-group`.
+Use instead of **sub-group**.
## that
-Do not use. Example: `the file that you save` can be `the file you save`.
+Do not use. For example:
+
+- Avoid: The file that you save...
+- Use instead: The file you save...
+
+## they
+
+Avoid the use of gender-specific pronouns, unless referring to a specific person.
+Use a singular [they](https://developers.google.com/style/pronouns#gender-neutral-pronouns) as
+a gender-neutral pronoun.
## useful
-Do not use. If the user doesn't find the process to be these things, we lose their trust.
+Do not use. If the user doesn't find the process to be useful, we lose their trust.
## utilize
@@ -159,5 +268,18 @@ Do not use. Use **use** instead. It's more succinct and easier for non-native En
Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml))
+## we
+
+Try to avoid **we** and focus instead on how the user can accomplish something in GitLab.
+
+- Avoid: We created a feature for you to add widgets.
+- Instead, use: Use widgets when you have work you want to organize.
+
+One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**.
+
+## whitelist
+
+Do not use. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
+
<!-- vale on -->
<!-- markdownlint-enable -->
diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md
index b634e2b93db..ddd44801ae9 100644
--- a/doc/development/documentation/testing.md
+++ b/doc/development/documentation/testing.md
@@ -210,6 +210,20 @@ Vale returns three types of results: `suggestion`, `warning`, and `error`:
of how to resolve the error. Errors break CI and are displayed in CI job output. See a list of
[error-level rules](https://gitlab.com/search?utf8=✓&snippets=false&scope=&repository_ref=master&search=path%3Adoc%2F.vale%2Fgitlab+Error%3A&group_id=9970&project_id=278964).
+#### Vale spelling test
+
+When Vale flags a valid word as a spelling mistake, you can fix it following these
+guidelines:
+
+| Flagged word | Guideline |
+|------------------------------------------------------|-----------|
+| jargon | Rewrite the sentence to avoid it. |
+| *correctly-capitalized* name of a product or service | Add the word to the [vale spelling exceptions list](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/spelling-exceptions.txt). |
+| name of a person | Remove the name if it's not needed, or [add the vale exception code in-line](#disable-vale-tests). |
+| a command, variable, code, or similar | Put it in backticks or a code block. For example: ``The git clone command can be used with the CI_COMMIT_BRANCH variable.`` -> ``The `git clone` command can be used with the `CI_COMMIT_BRANCH` variable.`` |
+| UI text from GitLab | Verify it correctly matches the UI, then: If it does not match the UI, update it. If it matches the UI, but the UI seems incorrect, create an issue to see if the UI needs to be fixed. If it matches the UI and seems correct, add it to the [vale spelling exceptions list](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/spelling-exceptions.txt). |
+| UI text from a third-party product | Rewrite the sentence to avoid it, or [add the vale exception code in-line](#disable-vale-tests). |
+
### Install linters
At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in
diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md
index f035b4d0888..31c38bc1446 100644
--- a/doc/development/documentation/workflow.md
+++ b/doc/development/documentation/workflow.md
@@ -63,7 +63,7 @@ To update GitLab documentation:
1. Follow the [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines).
NOTE:
-Work in a fork if you do not have Developer access to the GitLab project.
+Work in a fork if you do not have the Developer role in the GitLab project.
### Ask for help
View Lorry Controller Status