Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Editorial team

On this page

What this page is for

This part of the handbook is for the blog editorial team. If this isn't you, you may find what you are looking for in the blog handbook, which covers the process for opening an issue and merge request for your blog post, as well as getting reviewed and published.

Blog style guide

We use American English by default.

Acronyms

When using acryonyms or initialisms, ensure that your first mention uses the full term and includes the shortened version in parentheses directly afterwards. From then on you may use the acronym or initialism instead.

Example: A Contributor License Agreement (CLA) is the industry standard for open source contributions to other projects.

Below are some common acronyms and initialisms we use which don't need to be defined first (but use sparingly, see Tone of voice above):

Ampersands

Use ampersands only where they are part of a company's name or the title of a publication or similar. Example: Barnes & Noble

Do not use as a substitute for "and."

Capitalization

See below for styling of specific words.

Case

Use sentence case for all titles and headings.

Feature names

All GitLab feature names must be capitalized. If referring to a GitLab feature as part of a workflow rather than speaking about the feature itself, use lower case.

Examples: "GitLab Issue Boards are a powerful project management and collaboration tool." vs "The editorial team uses an issue board to track the progress of blog posts."

Job titles

We do not capitalize job titles, regardless of whether they appear before or after a person's name.

GitLab functions/departments/teams

These are elements that make up GitLab the company's organizational structure. Capitalize the name of the element, but not the word after:

Example: Engineering function, Security department

Proper nouns

Capitalize the first letter of a proper noun, regardless of how it is styled in a company's logo, for example.

Examples: Reddit, Lego

Contractions

We favor contractions ("can't," "didn't," "it's," "we're") to sound more human and less formal.

Dates

Months

Spell out, unless using the full date (see below).

Specific dates

Jan. 3, 2019 (abbreviate month, no rd after 3)

Headings and subheadings

These do not need to be full sentences. Do not include a period at the end of any headings.

Try to avoid vague blog post titles, especially beginning with continuous verbs ("-ing"). Make them active and descriptive so that readers know what they can expect to gain from reading the post.

Examples:

Reducing DevOps costs -> How to reduce DevOps costs

Beautifying our UI -> What we're doing to beautify our UI

Lists

Use * or - to create a bulleted list in Markdown. No period is necessary at the end of each bullet point.

Numbers

Numbers with four or more digits should include a comma.

Examples: 2,000; 100,000

In body copy

Spell out one to nine. Use numerals for 10 upwards. Try to avoid beginning a sentence with a number, but if unavoidable, spell it out.

In headings/subheadings

Use numerals. If at the beginning of a heading, capitalize the first word following.

Example: 3 Strategies for implementing a microservices architecture

Pronouns

Unless referring to someone in particular, use gender-neutral pronouns ("they", "them").

Punctuation

Only one space after a period is necessary.

Include one space after ellipses (… )

See below for when to hyphenate specific words.

We use en dashes (–) rather than em dashes (—). Include a space before and after the dash.

Use % instead of "percent" at all times.

Quotes

Quotation marks

Use double quotation marks for direct quotes, and single quotation marks for a quote within a quote. Single quotation marks may also be used for specialist terms or sayings.

Include punctuation in quotation marks.

Example: What do you think of the claim, "software is eating the world?"

Tense

When including direct quotations from interviewees in blog posts, we prefer to use the feature journalism style of present tense for verbs such as "said," "explained" etc.

Example: "Ruby was optimized for the developer, not for running it in production," says Sid.

Referring to interviewees

For blog posts, prefer referring to interviewees by their first names as this is less formal and more in keeping with our tone of voice.

Voice

Active voice is preferred to passive voice in blog posts. Voice describes whether the subject of a sentence receives or performs the action of a verb.

Example: "The GitLab community submitted 1 million merge requests in March 2019." (active) vs. "One million merge requests were submitted by the GitLab community in March 2019." (passive)

Word choice

When in doubt, use the "future" styling of a word. So, "internet" is not capitalized, "startup" is not hyphenated, etc.

Word list

How to spell and style commonly used words.

Appendix B: UK vs. American English

Use American spelling in your communications. Please consult this list of spelling differences.

Editorial review checklist

Style and language

Formatting

Finally