Recommended word list

To help ensure consistency in the documentation, the Technical Writing team recommends these wording choices. The GitLab handbook also maintains a list of top misused terms.

For guidance not on this page, we defer to these style guides:

@mention

Try to avoid @mention. Say mention instead, and consider linking to the mentions topic. Don’t use backticks.

2FA, two-factor authentication

Spell out two-factor authentication in sentence case for the first use and in section headings, and 2FA thereafter. If the first word in a sentence, do not capitalize factor or authentication. For example:

  • Two-factor authentication (2FA) helps secure your account. Set up 2FA when you first log in.

above

Try to avoid using above when referring to an example or table in a documentation page. If required, use previous instead. For example:

  • In the previous example, the dog had fleas.

Do not use above when referring to versions of the product. Use later instead.

Use:

  • In GitLab 14.4 and later…

Instead of:

  • In GitLab 14.4 and above…
  • In GitLab 14.4 and higher…

access level

Access levels are different than roles or permissions. When you create a user, you choose an access level: Regular, Auditor, or Admin.

Capitalize these words when you refer to the UI. Otherwise use lowercase.

administrator

Use administrator access instead of admin when talking about a user’s access level.

admin access level

An administrator is not a role or permission.

Use:

  • To do this thing, you must be an administrator.
  • To do this thing, you must have administrator access.

Instead of:

  • To do this thing, you must have the Admin role.

Admin Area

Use title case Admin Area to refer to the area of the UI that you access when you select Menu > Admin. This area of the UI says Admin Area at the top of the page and on the menu.

agent

Use lowercase to refer to the GitLab agent for Kubernetes. For example:

  • To connect your cluster to GitLab, use the GitLab agent for Kubernetes.
  • Install the agent in your cluster.
  • Select an agent from the list.

Do not use title case GitLab Agent or GitLab Agent for Kubernetes.

agent access token

The token generated when you create an agent for Kubernetes. Use agent access token, not:

  • registration token
  • secret token
  • authentication token

air gap, air-gapped

Use offline environment to describe installations that have physical barriers or security policies that prevent or limit internet access. Do not use air gap, air gapped, or air-gapped. For example:

  • The firewall policies in an offline environment prevent the computer from accessing the internet.

allow, enable

Try to avoid allow and enable, unless you are talking about security-related features.

Use:

  • You can add a file to your repository.

Instead of:

  • This feature allows you to add a file to your repository.
  • This feature enables users to add files to their repository.

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.

Alpha

Use uppercase for Alpha. For example: The XYZ feature is in Alpha. or This Alpha release is ready to test.

You might also want to link to this section in the handbook when writing about Alpha features.

and/or

Instead of and/or, use or or rewrite the sentence to spell out both options.

and so on

Do not use and so on. Instead, be more specific. For details, see the Microsoft style guide.

area

Use section instead of area. The only exception is the Admin Area.

associate

Do not use associate when describing adding issues to epics, or users to issues, merge requests, or epics.

Instead, use assign. For example:

  • Assign the issue to an epic.
  • Assign a user to the issue.

below

Try to avoid below when referring to an example or table in a documentation page. If required, use following instead. For example:

  • In the following example, the dog has fleas.

Beta

Use uppercase for Beta. For example: The XYZ feature is in Beta. or This Beta release is ready to test.

You might also want to link to this section in the handbook when writing about Beta features.

blacklist

Do not use blacklist. Another option is denylist. (Vale rule: InclusionCultural.yml)

board

Use lowercase for boards, issue boards, and epic boards.

box

Use text box to refer to the UI field. Do not use field or box. For example:

  • In the Variable name text box, enter a value.

bullet

Don’t refer to individual items in an ordered or unordered list as bullets. Use list item instead. If you need to be less ambiguous, you can use:

  • Ordered list item for items in an ordered list.
  • Unordered list item for items in an unordered list.

button

Don’t use a descriptor with button.

Use:

  • Select Run pipelines.

Instead of:

  • Select the Run pipelines button.

cannot, can not

Use cannot instead of can not. You can also use can’t.

See also contractions.

checkbox

Use one word for checkbox. Do not use check box.

You select (not check or enable) and clear (not deselect or disable) checkboxes. For example:

  • Select the Protect environment checkbox.
  • Clear the Protect environment checkbox.

If you must refer to the checkbox, you can say it is selected or cleared. For example:

  • Ensure the Protect environment checkbox is cleared.
  • Ensure the Protect environment checkbox is selected.

(For deselect, Vale rule: SubstitutionWarning.yml)

checkout, check out

Use check out as a verb. For the Git command, use checkout.

  • Use git checkout to check out a branch locally.
  • Check out the files you want to edit.

CI/CD

CI/CD is always uppercase. No need to spell it out on first use.

CI/CD minutes

Use CI/CD minutes instead of CI minutes, pipeline minutes, pipeline minutes quota, or CI pipeline minutes. This decision was made in this issue.

click

Do not use click. Instead, use select with buttons, links, menu items, and lists. Select applies to more devices, while click is more specific to a mouse.

collapse

Use collapse instead of close when you are talking about expanding or collapsing a section in the UI.

confirmation dialog

Use confirmation dialog to describe the dialog box that asks you to confirm your action. For example:

  • On the confirmation dialog, select OK.

Container Registry

Use title case for the GitLab Container Registry.

currently

Do not use currently when talking about the product or its features. The documentation describes the product as it is today. (Vale rule: CurrentStatus.yml)

Dependency Proxy

Use title case for the GitLab Dependency Proxy.

deploy board

Use lowercase for deploy board.

Developer

When writing about the Developer role:

  • Use a capital D.
  • Do not use bold.
  • 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:
    • Use: at least the Developer role
    • Instead of: the Developer role or higher

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 for guidance on disable. Use inactive or off instead. (Vale rule: InclusionAbleism.yml)

disallow

Use prevent instead of disallow. (Val