Blog style guide
Related pages
Why use the blog style guide?
The blog style guide covers styling, punctuation, spelling, and terminology guidelines for posts on the GitLab blog. If you have questions about writing, word usage, etc. that aren’t included in the style guide, feel free to reach out to the Editorial team (@sgittlen) or open a merge request with your suggested update and ping the team there.
A few best practices for effective writing
The blog editor may point out some of these common areas for growth in the comments section of the blog post. Here are a few things to keep in mind:
- Don’t start a sentence with “This” or “That”: It requires the reader go to the previous sentence to find out what you’re referencing. Instead, define what you’re saying outright.
- Don’t assume your reader knows what you’re talking about. Define key concepts and terms, and explain what particular products and businesses do.
- Add links to relevant documentation, issues, MRs, or past blog posts whenever possible. This allows the reader to click the link and learn more if they’re interested.
- If the blog editor needs to read your sentence more than once, they may ask questions about what you’re trying to say, or ask you to explain it. The editing process is conversation and collaborative, and may require a few asynchronous exchanges to help us get to a common understanding. The goal is always to help improve the clarity of ideas and language in the blog post, which will help us drive results!
When in doubt, go through the draft again but this time adopting the eyes of a reader instead of a storyteller. Also, it is always easier to edit something that someone else has written, it is much harder to edit your own copy. This is where peer reviewers and the editorial team comes in!
Contextualize your post
It’s also important to consider the context of the post. Ask yourself why it matters to the reader, and, if possible, connect your story to a broader industry issue. Don’t jump in straight away with what you want to tell the reader about without first giving some thought to and communicating why the reader should be interested. That type of context can “uplevel” your content and result in a better reader experience.
There are generally two ways to go about this:
1. Include a “sweep” paragraph near the beginning of your post to contextualize
The following prompts may help you determine what to write about here:
- What is the status quo?
- What problem are you trying to solve or what challenge are you hoping to address?
- What will the reader gain from reading your post? What will they learn?
You can see an example of “sweep” paragraphs at the beginning of this post on low-code/no-code tools, giving history and context to the topic before diving into the GitLab-specific story.
2. Uplevel the whole post
Example: “The trouble with technical interviews? They aren’t like the job you’re interviewing for” was originally planned to be just about how GitLab’s Frontend group redesigned its technical interviews. After discussion, it was decided that there was a broader story to tell here, because the GitLab story (redesigning Frontend technical interviews) was really addressing a greater, industry-wide problem, which is that technical interviews aren’t effective and aren’t always inclusive.
Not every post will be suitable for this treatment, so you and the Editorial team member reviewing your post can use your discretion. In some cases it may be appropriate to tweak just the title of the post to make it broader (e.g. “How GitLab CI helps solve common DevSecOps challenges”).
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):
- AFAIK - as far as I know
- ICYMI - in case you missed it (for social only)
- IIRC - if I recall correctly
- IRL - in real life
- TL;DR - too long; didn’t read
American English vs. British English
We use American English by default. Please consult this list of spelling differences.
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.”
Branch names
When writing the name of the branch, the best practice is to style it in back-ticks as opposed to quotation marks, italics etc. Example: sk-branch-name
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
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”
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)
Headlines
Please see headline advice in the blog handbook.
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 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.
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.
The exception to that would be when quoting from an event that was obviously in the past; in that case please use the past tense so the reader is not confused or misled.
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
We prefer that writers use active voice instead of passive voice in blog posts. Voice describes whether the subject of a sentence receives or performs the action of a verb. Learn more about tone of voice in this blog post by Grammarly.
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.
- Agile
- A is capitalized when referring to Agile methodology
- AI-powered DevSecOps platform
- AI-powered is always hyphenated
- powered and platform are always lowercase in written content (there may be exceptions when the term is used in design and brand assets)
- If GitLab precedes the term, Platform is capitalized but powered is not: GitLab AI-powered DevSecOps Platform
- all remote
- We refer to GitLab as an all-remote company (not remote friendly, remote first, or remote only)
- hyphenated only when appearing before a noun (“GitLab is an all-remote organization”/“GitLab is all remote”)
- Board
- when in reference to the GitLab Board or Directors or our Board members, Board is capitalized
- a board in general does not need to be capitalized
- built-in/built in
- always hyphenated when appearing before a noun e.g. “GitLab has built-in CI/CD.” Two words when used as a verb e.g. “GitLab comes with CI/CD built in.”
- cloud native
- not capitalized, and no hyphen, regardless of how it is used
- co-founder
- hyphenated, not capitalized
- continuous delivery, deployment, integration
- not capitalized
- developer
- use the abbreviation “dev” sparingly; do not capitalize
- DevOps
- D and O always capitalized
- E-Group
- references to E-Group should always include a capital E, hyphen, and a capital G
- emoji
- use emoji for singular and plural
- Git
- always capitalized
- GitHub
- GitLab
- G and L are always capitalized, even in GitLab.com
- internet
- not capitalized
- Kubernetes
- always capitalized, never abbreviated to K8s (except on social)
- lifecycle
- always one word
- Master
- we no longer use this term to refer to branches…please use main instead
- multicloud
- one word, no hyphen, lowercase m, lowercase c
- open source
- no hyphen, regardless of how it is used
- operations
- use “ops” sparingly; do not capitalize
- plugin
- always one word
- set up/setup
- two words for the verb, one for the noun (“How to set up a Kubernetes cluster”/“Let’s walk through the Kubernetes cluster setup process”)
- sign up/signup
- two words for the verb, one for the noun (“Sign up for a GitLab.com account”/“Upon signup, you will be sent a confirmation email”)
- startup
- no hyphen
- web
- not capitalized
Editorial review checklist
Diversity, Inclusion, and Belonging
We have a checklist for writers in the blog handbook to help guide a more inclusive writing process. The checklist below is for editors to ensure that our published content reflects our values of Diversity, Inclusion, and Belonging (DIB).
Are the images inclusive?
- Are images (cover image and any screengrabs) inclusive?
- Is the alternative text descriptive (for SEO and accessibility)? If not, tag the author or make the change yourself. Here are some tips on writing descriptive alternative text.
Is the writing inclusive?
- Does the post use inclusive language?
- Confirm that people featured in the post are referencing using their correct pronouns? You can do a quick check on the individual’s team page profile and Slack profile.
- Whenever possible, edit to remove extra words to keep sentences short and concise. For example: “The family is excited to buy their very own house” can be edited to read “The family is excited to buy a house”. These edits make the post easier for all readers to follow.
- Check that the writing is appropriate for a global audience. Flag any regional metaphors or United States-centric language.
- Ensure that all links are meaningful and descriptive (e.g. avoid link text such as “read here” or “this article”). Descriptive links are more useful and accessible for people using screen readers.
Ask the DIB team
- If you have a DIB question about the blog post, don’t just guess. Reach out to the DIB team or tag the leads of the appropriate team member resource group (TMRG) in the blog issue or merge request.
Style and language
- Does the post adhere to our style guide?
- Is it written in American English?
- Are all titles and headlines in sentence case?
ac0e3d5e)
