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

Editorial team

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.

We use American English by default.


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):


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."


See below for styling of specific words.


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

Brand and publication names

Ensure you style brand names consistently with how the company does.

Example: WiFi Tribe, DigitalOcean

The only exception to this is for brand names that are in all upper or lower case. Always capitalize the first letter, regardless of how it is styled in a company's logo.

Examples: Reddit, Lego

If the word "the" forms part of a brand or publication's name, capitalize it:

Examples: The Wall Street Journal, The Times

You can drop the "The" entirely if used as follows:

"We spoke to a Wall Street Journal reporter"


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



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.


Reducing DevOps costs -> How to reduce DevOps costs

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


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


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


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


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.


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 periods and commas inside ending quotation marks. Leave semi-colons, colons, and dashes outside of the quotation marks. Include other punctuation based on the sentence meaning.

Examples: Recently, an article was published stating, "Software is eating the world." What do you think of the claim, "Software is eating the world"? "Do you agree that software is eating the world?" wrote the author.


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.


Each blog post should be optimized for search engines. A primary keyword is a word/phrase that is repeated a few times in the blog post/headline (see below) and will help a search engine make our content "findable." A secondary keyword reinforces the first keyword by giving someone searching for content on the internet another way to find what they're looking for. In the spirit of MVC, let's focus on just making sure each blog post has a primary keyword (but you'll get bonus points if you can work a secondary keyword in!) A primary keyword might be "DevSecOps" while a secondary keyword might be "DevOps security tools" or "secure software development." Please note that while "keyword" is the commonly used term that does not mean it has to be a single word; it can certainly be a short phrase (also known as a long-tail keyword.)

We use Moz Pro, which is a straightforward way to search for keywords. You can enter a topic and then you'll get suggestions based on traffic volume. Choose a keyword and remember that often a long-tail version might work just as well and have less competition from other sources (example: DevSecOps vs. DevOps security tools). In an ideal world, your keyword or keyword phrase should be in the URL, the headline and the first paragraph. If some or all of that is not possible, alt-text for a photo, a caption or the tweet that appears on the bottom of the blog post are great ways to "sneak in" keywords.

If for some reason you don't have access to Moz or you're not finding anything that feels right, here's another more DIY SEO option.

  1. Start with the main topic of the post (example: DevSecOps)
  2. Visit Google Trends, enter your term and make sure to choose "worldwide." You can also enter other terms to compare it to (example: software development security). Scroll down and you'll see how popular your keyword is and you'll also be offered some alternate suggestions.
  3. Consider your keyword in context. The term "DevOps" will be popular but that also means there will be a lot of competition for it. But a long-tail keyword like "DevOps security tools" will have less competition.
  4. Once you've settled on a keyword it would be ideal, but not mandatory, to have it in the URL, headline and in the first paragraph.

Finally, digital marketing is putting together a searchable database of relevant keywords for GitLab that will be updated monthly. When that is ready a link will be available here.


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


Checklist for merging blog posts

When you are ready to merge a scheduled blog post, check the review app for the blog post:

Link to review app

When you've checked all these, go ahead and hit Merge. You can also check the boxes for Delete source branch and Squash commits but this isn't strictly necessary.

Merge button

Once you've pressed merge, go to the Pipelines page, which you can find in the menu on the left under CI/CD.

Shortcut to pipelines page

Find your merge pipeline, which will probably be near the top of the page. It will say Merge branch 'your-branch-name' into 'master'.

Merge pipeline

You can watch its progress there. Depending on your notification settings, you may get an email when your pipeline passes, or if it fails.

When your pipeline passes

Go to the blog homepage and your post should be visible there. Sometimes this takes a few minutes. When you see it, grab the link and share it in the #content-updates channel in Slack.

What happens if my pipeline fails?

If a pipeline fails when you try to merge something, it is usually not something you have done wrong! You can retry it, but if it still doesn't work, it's probably quickest to get an answer by sharing your MR link in #mr-buddies or #questions on Slack.

MR buddies

If you run into issues with your MR, pipeline, or Terminal, it's usually quickest to ask for help in the #mr-buddies, #git-help, or #questions channel on Slack (be sure to include a link to your MR!). If you don't get an answer that way, you can reach out to a Merge Request Buddy. The following team members have volunteered to be called on for assistance. You can also search for "Merge Request Buddy" on the team page.

Featuring Unfiltered posts

The Editorial team will monitor the GitLab Unfiltered blog for posts that are suitable for featuring on the branded blog on a weekly basis.

Process for reviewing and featuring Unfiltered posts

Every Monday, a member of the Editorial team will read new Unfiltered posts published during the previous week and select any posts that are likely to perform well on the branded blog for a full editorial review.

Criteria for a featured post

This is not an exhaustive list of criteria, as the Editorial team member will also use their best judgment regarding what tends to perform well on the branded blog.

Review process


If an Unfiltered blog post has been identified as a good candidate for featuring, the Editorial team member should open an issue in the project with the title "Feature Unfiltered post: [title of Unfiltered post]", using the feature-unfiltered-post issue template.

Include a link to the original post in the issue description, and @ mention the author of the post so that they are aware it is being reviewed for featuring on the branded blog.

Merge request review

Once the issue is open, the Editorial team member can create an MR for the full editorial review of the post, in the same way as net new posts that are submitted to the branded blog for review.

Checklist for reviewer:

This blog post was originally published on the [GitLab Unfiltered blog](/blog/categories/unfiltered/). It was reviewed and republished on yyyy-mm-dd.
{: .alert .alert-info .note}

When the author has reviewed and all outstanding threads resolved, they should reassign the MR to the Editorial team member to merge the changes.


Featured Unfiltered posts can be merged straight away, and don't need to be scheduled like brand new posts. When the edited post is live, the Editorial team member who merged should share a link in the #content-updates channel on Slack so the social team is aware that the post is now on the branded blog and can be shared on GitLab social channels.

The team will aim to have selected posts featured within a week of creating the issue. This may change depending on the availability of the post's author to review changes.