Language

For the main style guide page, see Documentation Style Guide.

GitLab documentation should be clear and easy to understand.

• Avoid unnecessary words.
• Be clear, concise, and stick to the goal of the topic.
• Write in US English with US grammar. (Tested in British.yml.)

Active voice

In most cases, text is easier to understand and to translate if you use active voice instead of passive.

For example, use:

• The developer writes code for the application.

Instead of:

• Application code is written by the developer.

Sometimes, GitLab as the subject can be awkward. For example, GitLab exports the report. In this case, use passive voice instead. For example, The report is exported.

Customer perspective

Focus on the functionality and benefits that GitLab brings to customers, rather than what GitLab has created.

For example, use:

• Use merge requests to compare code in the source and target branches.

Instead of:

• GitLab allows you to compare code.
• GitLab created the ability to let you compare code.
• Merge requests let you compare code.

Words that indicate you are not writing from a customer perspective are allow and enable. Try instead to use you and to speak directly to the user.

Building trust

Product documentation should be focused on providing clear, concise information, without the addition of sales or marketing text.

• Do not use words like easily or simply.
• Do not use marketing phrases like “This feature will save you time and money.”

Instead, focus on facts and achievable goals. Be specific. For example:

• The build time can decrease when you use this feature.
• Use this feature to save time when you create a project. The API creates the file and you do not have to manually intervene.

Anthropomorphisms

Do not attribute human qualities such as perception, intent, or awareness to software, systems, or data.

Describe what the system does mechanically, not what it experiences or intends.

Use:

• The field is removed before the response reaches the agent.
• A reason: is set on every error when the cause can be determined.

Instead of:

• The field is removed before the agent sees the response.
• A reason: is set on every error when the tool knows why it failed.

Tested in Anthropomorphism.yml.

Self-referential writing

Avoid writing about the document itself. For example, do not use:

• This page shows…
• This guide explains…

These phrases slow the user down. Instead, get right to the point. For example, instead of:

• This page explains different types of pipelines.

Use:

• GitLab has different types of pipelines to help address your development needs.

Tested in SelfReferential.yml.

Capitalization

As a company, we tend toward lowercase.

Topic titles

Use sentence case for topic titles. For example:

• # Use variables to configure pipelines
• ## Use the To-Do List

Feature names

Feature names should be lowercase.

However, in a few rare cases, features can be title case. These exceptions are:

• Added as a proper name to markdownlint, so they can be consistently applied across all documentation.
• Added to the word list.

If the term is not in the word list, ask a GitLab Technical Writer for advice. For assistance naming a feature and ensuring it meets GitLab standards, see the handbook.

Do not match the capitalization of terms or phrases on the Features page or features.yml by default.

Other terms

Capitalize names of:

• GitLab product tiers. For example, GitLab Free and GitLab Ultimate.
• 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.

Follow the capitalization style listed at the authoritative source for the entity, which might use non-standard case styles. For example: GitLab and npm.

Fake user information

Do not include real usernames or email addresses in the documentation.

For text:

• Use diverse or non-gendered names with common surnames, like Sidney Jones, Zhang Wei, or Alex Garcia.
• Make fake email addresses end in example.com.

For screenshots:

• Temporarily edit the page before you take the screenshot:

  1. Right-click the text you want to change.
  2. Select Inspect.
  3. In the Elements dialog, edit the HTML to replace text that contains real user information with example data.
  4. Close the dialog. All of the user data in the web page should now be replaced with the example data you entered.
  5. Take the screenshot.

• Alternatively, create example accounts in a test environment, and take the screenshot there.

• If you can’t reproduce the environment, blur the user data by using an image editing tool like Preview on macOS.

Fake URLs

When including sample URLs in the documentation, use:

• example.com when the domain name is generic.
• gitlab.example.com when referring only to GitLab Self-Managed. Use gitlab.com for GitLab.com.

Fake tokens

Do not use real tokens in the documentation.

Use these fake tokens as examples:

Contractions

Contractions are encouraged, and can create a friendly and informal tone, especially in tutorials, instructional documentation, and user interfaces.

Some contractions, however, should be avoided:

Possessives

Do not use possessives ('s) for proper nouns, like organization or product names.

For example, instead of Docker's CLI, use the Docker CLI.

For details, see the Google documentation style guide.

Prepositions

Use prepositions at the end of the sentence when needed. Dangling or stranded prepositions are fine. For example:

• You can leave the group you’re a member of.
• Share the credentials with users you want to give access to.

These constructions are more casual than the alternatives:

• You can leave the group of which you’re a member.
• Share the credentials with users to which you want to give access.

Acronyms

If you use an acronym, spell it out on first use on a page. Do not spell it out more than once on a page.

• Titles: Try to avoid acronyms in topic titles, especially if the acronym is not widely used.
• Plurals: Try not to make acronyms plural. For example, use YAML files, not YAMLs. If you must make an acronym plural, do not use an apostrophe. For example, use APIs, not API's.
• Possessives: Use caution when making an acronym possessive. If possible, write the sentence to avoid making the acronym possessive. If you must make the acronym possessive, consider spelling out the words.

Numbers

For numbers in text, spell out zero through nine and use numbers for 10 and greater. For more information, see the Microsoft Style Guide.

For numbers in the UI, see Pajamas.

Dates and times

Use the month day, year format for dates, and use AM and PM for times. For example:

January 3, 2026 at 10:30 AM

For additional details, see the Microsoft Style Guide.

For dates and times in the UI, see Pajamas.