Blog Handbook
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.
Legal review process
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
Other related pages
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
- Did you select an inclusive cover image and/or screengrab?
- Write descriptive alternative text for all inline images and screengrabs. Alternative text is important for SEO and accessibility. Read this article from Moz to learn more about writing alternative text.
- 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.
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
- Is your blog post biased? We all have unconscious biases. Take our recognizing bias training, check the list of unconscious biases in our DIB handbook page and practice strategies for recognizing and managing yours.
- If you still have questions, don’t hesitate to tag the editorial team lead @sgittlen, leads of the appropriate team member resource group (TMRG) in your blog issue, or email diversityinclusionandbelonging@gitlab.com with your questions.
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 DevOpsdevops platform
- posts mentioning GitLab’s DevOps Platform, or DevOps platforms more generically.DevSecOps
- posts more generally about DevSecOpsDevSecOps platform
- posts mentioning GitLab’s DevSecOps Platform, or DevSecOps platforms more genericallyengineering
– technical, actionable content. Anything covering how to do something, use something, or solve a problem should fall under this categoryai-ml
– posts that focus directly on AI/ML in the platform or in the industry as a wholeopen source
– stories from or about our community, users, or the wider open source communitycareers
– posts about careers, salaries, education, and moreculture
– posts about remote work, working together, or GitLab cultureinsights
– industry, data, newsjacking, developer survey, etc.news
– company or product announcements (including policy changes, operational announcements, and breaking changes), news, or eventssecurity
– security-related postsreleases
- release posts, security and patch releases. Posts in thereleases
category need to be in thesites/uncategorized/source/releases/posts
directory, notsites/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
- 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)
|
|
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 theResolution
field. Preview will estimate what the resulting image size will be before you clickOK
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.
Git Guide for Blog Contributors
GitLab Release Posts
b8e1c564
)