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.
The GitLab blog exists for our audience and we serve our audience first. Without an audience, blog content cannot support our objectives. Every blog post published on the GitLab blog should be crafted with our audience needs and wants in mind. Our core audience is software developers and this guides our strategy.
The GitLab blog is not self-serving; if content is purely promotional and adds no value to our readership, it will not be published.
We measure success by tracking the following metrics:
Mission statement: We cover the life of the software developer and anyone involved in the software development lifecycle (e.g., ops, sec, test professionals*). These are our core audience of users, who are influential in adopting and expanding the use of GitLab in their workplaces and communities. Our aim is to help our audience continually improve in all aspects of their work lives. We cover topics ranging from career and skills development and efficient and effective collaboration to sharing tutorials and lessons from our engineering org to new technology developments, trends, and ideas.
Please see Attributes of a successful blog post for examples of stories that perform well on our blog.
The blog is not the permanent place for tutorials, which should live in the docs and should be linked to when relevant.
*See user personas
Based on analyses of traffic to blog posts, below are some topics and types of blog posts that usually resonate with our audience and draw the most traffic.
Below are some examples of types of posts that we have found not to be successful with our audience. To prioritize results, we try to avoid publishing these types of posts, and have made suggestions for alternatives that may perform better.
For context, we aim for a blog post to achieve a minimum of >1,000 unique views in its first month.
With the exception of big news, for example a funding announcement or making paid features open source, promotional announcements do not tend to draw lots of traffic. We encourage team members to check out our [best practices in the blog handbook], which may help contributors to adjust the angle or substance of their post to be more appealing to our audience. In some cases a straightforward announcement is more appropriate than attempting to tell a story with the news, in which case the Editorial team member reviewing the draft will just do a light proofread and check for formatting rather than a more in-depth edit.
Please see [best practices documented in this handbook].
These posts don't form part of our editorial strategy as they serve only as communications to users or customers. We will only proofread these and check for formatting.
Posts focusing on GitLab features or capabilities don't consistently draw traffic.
Please see best practices for GitLab feature posts.
Straightforward event or webcast recaps don't perform well, in part because people look to other major or tech-specific news sources for recaps of major events. You can see a more detailed audit of event-supporting blog posts here.
Please see best practices for event coverage.
These are often requested from within GitLab, but our external audience has less of an appetite for these types of posts!
A better approach is to focus on a specific theme or product area, as in GitLab CI/CD's 2018 highlights. Think about what information someone might be searching for as opposed to what we want to tell them – they are probably looking for a solution to a problem or how to improve on something, rather than simply interested in what GitLab has been doing.
Visionary/speculative posts don't seem to hold much appeal for our readers, who are often looking for more tactical or informative posts on our blog.
There needs to be real news, opinion, or practical content for a post to do well.
We review traffic to blog posts on a quarterly basis. You can view past analyses below:
With the exception of time-sensitive announcements and news, we are aiming to have blog posts scheduled two weeks ahead.
The editorial calendar documents when posts will be published, as well as industry awareness days and anniversaries we may cover. Please bear this in mind when requesting a specific publish date for a post. If you can't view the calendar, please make sure that you are logged into your GitLab G Suite account.
Please note that all dates are subject to change to accommodate urgent posts and announcements.
blog post: every blog post idea, proposal, draft, etc. MUST have this label
priority: blog posts that should be worked on immediately (please provide a rationale in your issue description)
Blog::Pitch: blog post ideas that are waiting for triage
Blog::Planning/in progress: accepted pitches and blog posts that are assigned to a member of the Content Marketing/Editorial team
Blog::Review: blog posts that are ready for an editorial review
Blog::Freeze: blog post is being reviewed by the Editorial team. No additional changes should be made until the label is lifted.
Blog::Waiting for author: blog posts that have been reviewed by the Editorial team and assigned back to the author to address feedback or approve for scheduling
Blog::Scheduled: Blog posts that have completed reviews and are scheduled for publishing
Guest/Partner post: blog posts that are authored and submitted from a contributor outside of GitLab
customer story: blog posts that include a customer interview
CEO interview: blog posts submitted by the GitLab CEO and require their subject matter expertise
Every Monday, a member of the Editorial team reviews blog post pitches. There is a recurring event on the Editorial calendar for every Monday. The Editorial team member reviewing pitches that week is invited to the event.
@cweaver1for product-related stories or
@JMLesliefor company-related or corporate stories.
Following the review above, the pitch should fall into one of three categories:
Blog::Planning/in progresslabel applied
Blog::Planning/in progresslabel applied
When responding to the person who pitched, be sure to include your rationale for your response and any relevant data or examples to justify your decision.
In addition to reviewing pitches submitted by team members, the Editorial team also actively sources topics for potential blog posts in the following ways:
During quarterly traffic analysis, identify high-traffic blog posts (published at any time, not necessarily from that quarter).
We can optimize these in a few ways:
Reach out to the blog post author to find out if there is an update to the story that might make a good blog post, or if they have another story to share. You can do this by opening an issue for a new blog post and pinging the author there.
This is a good idea for engineering posts that explain in depth how we built a feature, completed a major migration, or fixed a bug. These posts don't age poorly because they describe something that has already happened. We don't need to keep them current in the same way as a tutorial, but there might be more to the story now that time has passed.
Update the blog post and republish it, with a link to the original post. We can do this either by reaching out to the author of the post, or if the author is not available and technical knowledge is required, we can open a Strategic Marketing Support Request to ask Technical Marketing to take it on.
This works for tutorials and how-to posts that are no longer current. Here is an example of an updated blog post.
This approach is suitable for older blog posts covering high-level, foundational topics that don't age (DevOps fundamentals, CI best practices, etc.) and which aren't specifically about GitLab features or functionality.
The #trending channel is for team members to surface new story ideas to Editorial. Anyone is welcome to join and can share links to news or opinion that could be worth pursuing as a blog post or in another content format (e.g. video).
We know that team members often share noteworthy news or developments in other channels – the difference here is the channel will help the Editorial team to aggregate and curate items that have strong blog post potential. The content can be anything that's relevant to our audience and within our blog scope.
If you are planning to write or even just considering writing a blog post:
Proposal, describe your proposed blog post topic
April blogs 2020)
Please ensure that you update:
If the post is postponed and you don't yet have a specific reschedule date, please remove:
Each week, one blog post is selected as the featured post on the blog homepage.
Ahead of the beginning of the month, the managing editor will open a
featured post issue in the Editorial project, listing the blog posts scheduled to go live in the coming month.
Editorial team members will nominate a post to be featured for each week, based on the following criteria:
When the featured post for a given week has been agreed on:
featured postissue description to confirm the featured post for that week
featured postissue where this was decided.
The managing editor will review the issue at the beginning of each week to ensure the schedule is up to date, any rescheduled/new posts have been accounted for, and that a featured post has been confirmed for the coming week.
At the end of the month, close the
featured post issue.
Some blog posts may need the review and approval of other groups at GitLab before publishing. In each of the below cases, the relevant internal approvers are identified.
When pinging these team members for review and approval, let them know that they are being asked to assess if the blog post introduces any potential risk to GitLab (our reputation or relationships with our partners, customers, community, or investors), and if so how to mitigate that risk.
We are not asking them to review for grammar/typos/style or other editorial elements. This is to be respectful of reviewers' time and to avoid duplicating work or confusing matters (in case a particular angle or words have been chosen for strategic or SEO purposes). If the reviewer identifies inaccuracies or language that may pose a risk to GitLab, that should be raised and addressed. In some cases (e.g. security topics) making sure we have provided sufficient context for all potential readers (not just the intended audience) is enough to mitigate the risk.
In each case, final approval must be documented on the merge request or issue for the blog post. If the reviewer gives approval via Slack or another channel, please leave a comment to indicate so.
Most blog posts concerning third parties are proposed and managed by Partner Marketing in collaboration with the third party in question. Occasionally such posts are proposed by other team members, in which case they should tick the relevant box on the blog post pitch issue and follow those instructions:
If the post is about one of GitLab's Technology Partners, including integration partners, mention @saraedavila and @arashidi, apply the Partner Marketing label, and see the blog handbook for more on third-party posts
If the blog post discusses a partner in depth, the person pitching should follow the blog handbook instructions for engaging Partner Marketing and Alliances for review and approval.
If a blog post is about a GitLab customer, the team member proposing the post should indicate this in their pitch issue by ticking the relevant box and following the instructions:
If the post is about one of GitLab's customers, mention @KimLock and @FionaOKeeffe, apply the Customer Reference Program label, and see the blog handbook for more on third-party posts
Communication of changes that will impact GitLab customers/users should be initiated by opening an announcement request per the PR handbook. If it's agreed by PR and Editorial that we will publish a blog post to communicate the news, the PR team member involved must confirm if they need to approve the post before publishing.
All blog posts related to the Board must be reviewed by Legal prior to publication. Ideally, Legal should be looped in as early as possible. Team members pitching blog posts need to check the following box in their pitch issue if this is the case:
Indicate if this post requires additional approval from internal or external parties before publishing
If the team member is unsure who from Legal to ping for approval, share in #legal on Slack.
Most blog posts requiring approval are accounted for above, but occasionally there may be other topics that are potentially sensitive and should be run by PR and possibly Legal for risk assessment before proceeding.
In these cases, please check the following box on the blog post issue and follow the instructions:
If wide-spread customer impacting or sensitive
- Add sensitive label
- Mention @nwoods to give her a heads up ASAP
Example: Our journey to a more diverse and inclusive workplace is on a hot-button issue, where GitLab is committing to taking action that we need to ensure we are prepared to follow through on.
The Editorial team will monitor the GitLab Unfiltered blog for posts that are suitable for featuring on the branded blog on a weekly basis.
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.
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:
Team members are strongly encouraged to work handbook first and to start with an MR. Whether a proposed change comes up in discussion on Slack, on GitLab, or in a meeting, or you just have an idea you would like to contribute, please open an MR to suggest the change, or open an issue in the Editorial project if you're not sure what change to make or want to put an idea up for discussion with the team first.
If you open an MR, please assign it to the managing editor to merge, and ping the rest of the Editorial team so everyone is aware of the change and can contribute to the discussion. Looping everyone in, even in cases where a change has been discussed and agreed on in a meeting, for example, is to ensure that the MR accurately captures what was agreed on, and that the whole team is aware of and understands any changes in case we need to explain anything to team members from other groups.
If the managing editor is unavailable, you can assign to another Editorial team member to merge, but please cc the managing editor so they are aware of the changes.
Note: This principle applies to process changes. Don't worry about pinging everyone if you open an MR to fix a typo or a broken link!
The blog style guide covers styling, punctuation, spelling, and grammatical 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 (@vsilverthorne) or open a merge request with your suggested update and ping the team there.
If you're looking for tips to improve your writing and storytelling, please see Writing blog posts – best practices below.
We review traffic to blog posts on a quarterly basis. You can view past analyses and takeaways in the Editorial team handbook, but below are the key points for all team members to keep in mind.
It's clear that technical/actionable/how-to content attracts the most blog readers and thus should be the focus of the majority of the content we create for the blog.
When writing a blog post, please keep the reader in mind. This person has more than likely searched for a topic or a trend and is looking for comprehensive content with a clear takeaway. Write to this person and consider the tone and the language that will best get your point across.
Our "How to pitch a blog post" section has some tips and prompts to help you prioritize our audience when planning your blog post.
It is important to have empathy for your reader. What this means is putting yourself in the position of the reader when writing or reviewing a blog post. Oftentimes, we write similarly to how we talk or think, which can lead to fractured phrasing and other patterns that can make it trickier for the reader to follow along. Remember: The reader doesn't have the background knowledge that the writer does. A good rule to remember is always write in a way that helps your reader move forward, and never requires them to go back to the previous sentence.
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:
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!
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:
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" – see below).
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):
We use American English by default. Please consult this list of spelling differences.
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."
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:
See below for styling of specific words.
Use sentence case for all titles and headings.
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."
We do not capitalize job titles, regardless of whether they appear before or after a person's name.
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
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).
Jan. 3, 2019 (abbreviate month, no
rd after 3)
Please see headline advice in the blog handbook.
- 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
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.
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.
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.
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.
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.
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.
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)
When in doubt, use the "future" styling of a word. So, "internet" is not capitalized, "startup" is not hyphenated, etc.
How to spell and style commonly used words.
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 are in the process of switching SEO tools so if you need help please reach out to a member of the editorial team for guidance. In general, though, 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.
Here is another more DIY SEO option.
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.
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).
gitlabbeen added to the
author_twitterfield if the author doesn't wish to use their own handle?
Descriptionfield copy fit on the tile on /blog?
open sourceit is best to remove it.
.html.md.erband that the newsletter sign-up form is included in the post, if appropriate. Don't include it if there are other CTAs in the post (for example, directing people to sign up for a webcast or watch a video).
When you are ready to merge a scheduled blog post, check the review app for the blog post:
featured: yesfrom the frontmatter accordingly.
When you've checked all these, you can tick the boxes for
Delete source branch and
Squash commits but this isn't strictly necessary.
Go ahead and hit
Start merge train or
Add to merge train. If the blog post does not have to be live ASAP, feel free to join the train. Otherwise you can just choose "Merge immediately" from the dropdown menu to the right.
You can find more information about merge trains here.
Once you've started or joined a merge train, go to the Pipelines page, which you can find in the menu on the left under CI/CD.
Merging a blog post requires two pipelines to pass. Find your first merge pipeline, which will probably be near the top of the page. It will say
Merge branch 'your-branch-name' into 'master'.
You can watch its progress there. Depending on your notification settings, you may get an email when your pipeline passes, or if it fails.
If it passes, a final pipeline will kick off:
When this passes, proceed to the next step.
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.
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.
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.
To run a paid promotion to blog posts, a series, or PathFactory track, plan at least four weeks ahead to gather all necessary assets, and coordinate with other groups.
Things to note: