Blog Handbook

Everything you need to know about suggesting and publishing a post on the GitLab Blog.

Welcome to the GitLab Blog handbook! The GitLab Blog is managed by the Content Marketing team. The managing editor of the blog is Sandra Gittlen (@sgittlen).

What is a blog post

At GitLab, blog posts largely focus on sharing helpful information with the audience (DevSecOps professionals). When you suggest or write a blog post, always consider what it offers the reader. If the post is more internal-focused or a personal essay of sorts, it is likely not a fit for the blog (but could go on your personal LinkedIn page).

Blogs fall into the following categories:

  • Technical tutorials/how-tos
  • Point of view/thought leadership
  • Introduction to features and capabilities
  • Open source community
  • Customer case studies/interviews
  • Company announcement (done in partnership with Executive comms team)
  • Feature/change/etc. announcement
  • Guest blog to highlight partnerships/alliances

Who can publish content to the GitLab blog?

Everyone can contribute at GitLab. For the blog, this means we welcome your blog suggestions, ideas, and drafts. However, the main blog is one of the many official voices of GitLab – meaning content that is published there must be carefully vetted to ensure we are accurately representing GitLab – both the company and the product. The Blog Managing Editor and the Director of Global Content Marketing are the directly responsible individuals (DRIs) for the official GitLab blog and are tasked with this responsibility.

Partner, alliance, and customer contributor guidelines can be found here.

How to suggest a blog idea - NEW PROCESS

Please create an issue using the blog submission template.

  • Answer all the questions on the template. They help us provide feedback on your idea.
  • Submit your idea at least two weeks before your targeted publication date.
  • For corporate/comms requests or blogs on a tight turnaround, please submit an issue and reach out to @sgittlen directly.

The blog editor will review the pitch and either a) greenlight the post, b) offer suggestions for improvements, or c) explain why the idea might not be a fit for the blog and offer other ideas for getting the message out.

How to submit a blog draft once your idea is approved

Once a blog pitch is approved, the author will use the Blog Submission template (Google Doc) to write the blog, ensuring the Google Doc is linked in the issue. All fields in the template will have to be completed for the blog team to accept the submission.

The author will tag @sgittlen in the issue, put the doc link in a comment, and share the Google Doc once it is ready to be edited (after all necessary approvals and reviews have been completed). Note: All images must be included inline in the Google Doc.

Note: All blog submissions now require a call to action or CTA and you will be asked to provide one in the blog draft template. A CTA is what you want the reader to do next after reading your blog. Do you want them to go to another page and learn more, sign up for a trial, register for a webinar, view a demo, etc.? We will be able to track the CTA as part of our overall blog metrics.

The blog edit process

The blog team will communicate initial edits/questions for the author using the issue and Google Doc. The blog team will then put the blog into the CMS and, if necessary, share a preview link with the author/DRI. Note: The blog will be published from Contentful.

If changes are needed post-publication, the author will reach out to the blog team via Slack and explain the change. Note: We can no longer use MRs for changes/updates.

The blog team will share the blog’s URL with the author once it is published.

Publishing of blog posts occurs according to an editorial calendar. However, that is subject to change based on blogs that are urgent. The blog team will update authors as to their expected publish dates.

Some blog posts must be reviewed by legal, in accordance with our Materials Legal Review Process/SAFE program. Authors are responsible for reviewing SAFE guidelines and getting Legal approval before sharing the Google Doc with the blog team. This process can take time, so please plan target publication dates accordingly.

GitLab has a bias for action, and the Blog team is no different. However, the GitLab Blog is a public-facing asset and represents the company. If the Blog team has concerns or questions about the information contained in the blog post, the Blog team has the authority to hold a blog post until Legal, Corporate Commmunications, Partner Marketing, the CMO, etc., can review the blog post to mitigate any potential risk for the company.

Learn more about the SAFE Guidelines by reading the handbook page and following the Materials Legal Review Process.

Communication with Blog team

Chat channels:

  • Use #content for questions (also tag @sgittlen)
  • Use #content-updates to see updates on recently published articles
  • Slack @sgittlen directly
  • Add newsletter content requests to this issue

Considerations when drafting a blog

Diversity, Inclusion, and Belonging (DIB) checklist for blog writers

It is important that our blog content represents our company values of diversity, inclusion, and belonging. Not all of these points will be relevant to your blog post, but they are important values and practices to be mindful of throughout the writing process. The blog editorial team tries to check for these things, but it is better if all content is created with these values and practices in mind. Tag us or a member of the DIB team if you have questions!

Inclusive formatting

Inclusive writing

  • Write short and concise sentences. Clear writing with short sentences makes it easier for the reader to follow along.
  • Limit your use of jargon, and if you must use a jargon-y term, define it on the first instance.
  • GitLab is a global team with a global community, so you want to write for a global audience. This means limiting your use of regional metaphors and not writing in a manner that is United States-centric.
  • Does the post use inclusive language?
  • Is every individual in the blog post quoted using their preferred pronoun? Tip: If you don’t know someone’s preferred pronoun, just ask them. They should also be included on the team page profile and Slack profile.

More DIB writing tips

Blog categories and tags

Categories

Use only one of the following categories per post. Do not change the capitalization, spelling, or anything else, otherwise you’ll create another category, which is something we don’t want to do accidentally.

If you’re not sure which category your post belongs in, just put a placeholder in your MR and leave a comment for your reviewer noting that.

  • DevOps - general reference to DevOps
  • devops platform - posts mentioning GitLab’s DevOps Platform, or DevOps platforms more generically.
  • DevSecOps - posts more generally about DevSecOps
  • DevSecOps platform - posts mentioning GitLab’s DevSecOps Platform, or DevSecOps platforms more generically
  • engineering – technical, actionable content. Anything covering how to do something, use something, or solve a problem should fall under this category
  • ai-ml – posts that focus directly on AI/ML in the platform or in the industry as a whole
  • open source – stories from or about our community, users, or the wider open source community
  • careers – posts about careers, salaries, education, and more
  • culture – posts about remote work, working together, or GitLab culture
  • insights – industry, data, newsjacking, developer survey, etc.
  • news – company or product announcements (including policy changes, operational announcements, and breaking changes), news, or events
  • security – security-related posts
  • releases - release posts, security and patch releases. Posts in the releases category need to be in the sites/uncategorized/source/releases/posts directory, not sites/uncategorized/source/blog/blog-posts. Please see the Release Post handbook for more.

Tags

These are included to help readers find similar posts if they are interested in a particular subject. Tags appear at the top of each blog post, and clicking on a tag takes you to /blog/tags where you can view all tagged posts and browse by tag.

You can include as many tags as you like, separated by commas. Please only include tags from the following list, and note that they are case sensitive.

  • agile
  • AI/ML
  • AWS
  • bug bounty
  • careers
  • CI
  • CD
  • CI/CD
  • cloud native
  • code review
  • collaboration
  • community
  • contributors
  • customers
  • demo
  • design
  • developer survey
  • DevOps
  • DevOps platform
  • DevSecOps
  • DevSecOps platform
  • events
  • features
  • frontend
  • Group Conversations
  • git
  • GitOps
  • GKE
  • google
  • growth
  • inside GitLab
  • integrations
  • kubernetes
  • news
  • open source
  • partners
  • patch releases
  • performance
  • product
  • production
  • releases
  • remote work
  • research
  • security
  • security releases
  • security research
  • solutions architecture
  • startups
  • testing
  • tutorial
  • UI
  • user stories
  • UX
  • webcast
  • workflow
  • zero trust

Media embeds

We limit media embeds to the following providers:

  • YouTube for video
  • CodePen for code samples
  • Google Docs for collaborative text
  • Google Sheets for sharing spreadsheets
  • Google Slides for sharing slides

Adding code blocks

Below are the two types of code blocks we commonly use on the blog. Find a number of other options in the Markdown guide.

Inline code

We use this for short words or phrases included in a paragraph. For inline code, surround the word or code with single backticks (`).

Example:

This is an `in-line` code block.

Results in:

This is an in-line code block.

Fenced code blocks

“Fenced” code blocks look like the block below. We use these for longer code snippets. To create a fenced code block, put triple backticks on one line directly above and one line directly below the code.

this is my code block
   here's another line
end

Highlighted code

Syntax highlighting helps make code easier to read. In order to enable syntax highlighting please append the language type at the end of the code block. The name matters because every language is highlighted differently.

Example (not highlighted):

```code goes here```
document.querySelectorAll('a[href^="#"]').forEach(elem => {
    elem.addEventListener('click', e => {
        e.preventDefault();
        let block = document.querySelector(elem.getAttribute('href')),
            offset = elem.dataset.offset ? parseInt(elem.dataset.offset) : 0,
            bodyOffset = document.body.getBoundingClientRect().top;
        window.scrollTo({
            top: block.getBoundingClientRect().top - bodyOffset + offset,
            behavior: "smooth"
        });
    });
});

Versus (highlighted javascript):

```code goes here```javascript

(or other languages/syntaxes such as yaml, ruby, sql, etc)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
document.querySelectorAll('a[href^="#"]').forEach(elem => {
    elem.addEventListener('click', e => {
        e.preventDefault();
        let block = document.querySelector(elem.getAttribute('href')),
            offset = elem.dataset.offset ? parseInt(elem.dataset.offset) : 0,
            bodyOffset = document.body.getBoundingClientRect().top;
        window.scrollTo({
            top: block.getBoundingClientRect().top - bodyOffset + offset,
            behavior: "smooth"
        });
    });
});

Preparing images

  • If creating an original cover image, the dimensions should be 1800px x 945px for optimal quality on all displays.
  • All images should aim to be less than 1MB. JPEGs tend to be smaller than PNGs so use JPEGs when possible.
  • To resize in Preview go to Tools, Adjust size and adjust the entry in the Resolution field. Preview will estimate what the resulting image size will be before you click OK to confirm.
  • Keep all the images the same width.

Screenshots

For technical/tutorial posts, please illustrate your examples with code blocks or screenshots. Be consistent with your examples. E.g., if you are using a generic URL to exemplify your steps domain.com, be consistent and keep it domain.com, throughout the post.

  • Static images should be used to illustrate concepts, provide diagrams, elements of the UI or orient the reader.
  • Images should not be used to render commands or configuration which would prevent someone being able to copy and paste.
  • Animated GIFs can be used sparingly where you need to show a process or some event happening over the course of time or several actions, though they should not replace text descriptions or instructions.
  • Use screenshots to identify and localize specific parts of the screen. There are great tools for doing so. For example, Nimbus Screenshot (browser extension), Mac screenshot, Snipping Tool for Windows, and Screenshot Tool for Ubuntu.

Important security point: Do not expose your personal details by using your real tokens or security credentials. Use placeholders such as [project's CI token] stub instead. Or blur them if displayed on screenshots.

Embedding videos

Please see the Markdown Guide for instructions for embedding videos from YouTube and other sources.

Embedding tweets or Instagram posts

Please see the Markdown guide for instructions for embedding posts from social media.

Creating GIFs

Animated GIFs are very useful to illustrate short dynamic processes, which might be easier to understand with this kind of resource. There are a few ways to create animated GIFs, one of them is using [Giphy Capture], a light-weight app for Mac.

Avoid GIFs with a huge file size, they will be difficult to load for users with bad internet connection. In those cases, you can either cut the GIFs in smaller pieces, or record a video, or use a sequential image.


Blog dashboard
How to use the GitLab blog performance dashboard.
Git Guide for Blog Contributors
A guide for working with Git, terminal, and the www-gitlab-com repository
GitLab Release Posts
Guidelines to create and update release posts