Editorial handbook

Editorial strategy

The Editorial Strategy for the Sourcegraph blog builds on our Content Strategy.

As one of Sourcegraph’s primary channels for generating awareness, the blog should play a key role in establishing the brand and our credibility with our audience. Beyond the blog, contributions to external publications and spin-off programs such as newsletters make up an editorial ecosystem.

In the context of content marketing, editorial content is defined by Power Digital Marketing as “content that is not explicitly aimed at selling something”.

Most technology brands have a corporate blog to support their content strategy, driving traffic through referrals and SEO, to build authority, credibility, and trust with their audience. Some brands have a separate engineering blog (for example, Netflix, Uber, Airbnb), which works well for consumer-facing brands whose customers are not necessarily interested in how the technology is built. For the most part however, corporate blogs tend to publish a blend of editorial and promotional content, ranging from tutorials and how-tos, engineering deep dives and product spotlights, to analyst report accolades, customer stories and company news.

With so much potential content to share, an editorial strategy helps to guide our decision making. It forces us to keep our audience’s needs top of mind and ensure that each blog post is set up for success by always offering something of value to our readers, maintaining a high quality bar, and aligning with broader marketing themes and objectives.

Editorial principles

The editorial strategy for Sourcegraph’s blog draws on the same principles that inform our overall content strategy:

  1. Quality over quantity. We do not sacrifice quality for quantity, and we take our reputation as a content producing company seriously. We respect our audiences’ time and thus, we respect the creative process and allow ample time for content creation.
  2. Audience-first mentality. We prioritize the needs of our audience over our own. Our content offers useful and actionable information regardless of whether the reader uses Sourcegraph or not. Content marketing does not equal advertising.
  3. Keep it helpful and simple. We make it easy to find, consume, and share our content. We create content that is intelligent, thoughtful, and accessible to all and apply user experience best practices. We don’t engage in fear mongering or share vapid content.

All blog posts and other editorial content need to align with the above principles, and we will vet content at all stages of production to ensure it meets our editorial standards:

  1. At the pitch stage: Wherever the idea comes from (within editorial, marketing, the rest of the company, or externally), at this stage we evaluate what value the proposed content will offer the reader. Is it helpful and simple? What do we hope they will learn or take away from the post? Are we putting the audience’s needs ahead of our own? (That is, are we helping them to learn something, solve a problem, or even entertain them, rather than just pushing a particular product feature?)
  2. At the review stage: Is the draft delivering on the pitch? Have we provided enough context or background information? Is it written in plain language and structured so it’s easy to read?
  3. After publishing: We will monitor performance of content to assess how it’s being received by our audience, and iterate on our strategy based on what we learn.

Mission statement

In one sentence: “Insights, tips, and technology to help you hone your craft and grow your career.”

The Sourcegraph’s blog primary function is to serve our developer audience: to be a source of information, inspiration, and delight. We want to help make developers’ jobs easier by surfacing technology, tips, and ideas to improve efficiency, grow in their careers, and hone their craft. We will do this by applying the above principles rigorously to all content that we publish.

The secondary function of the blog is to grow awareness of Sourcegraph’s brand. Fulfilling this function is a direct result of the first: we can’t establish Sourcegraph as a trusted, respected developer brand without serving our audience first.

Priority content

The buckets outlined below are an internal reference and guideline. Although there are three buckets here, content we may publish isn’t limited to these, and we may publish more of one type of content than others.

  1. Inside Sourcegraph engineering: How we built X, scaled Y, debugged Z. These are meaty deep dives into the process of building and iterating on Sourcegraph the product and engineering org. Got code snippets? Graphs and charts? Links to PRs? We’ll take them all. Even though we may talk about Sourcegraph as part of these stories, the focus is on the technical work behind the product rather than the product itself.
  2. Tutorials/how tos: These practical posts show readers how to solve a problem or improve on a skill. Better code reviews, communication and collaboration advice, and productivity tips are examples of topics we might tackle here.
  3. Customer/user stories: Stories highlighting cool things our customers and users are doing with or because of Sourcegraph. We’ll collaborate with customer marketing and community on these.

To view sample categories and feature stories, team members can check out the Editorial Strategy RFC.

Editorial process

Writing is a process, and thus, our publishing guidelines are designed to aid the writer in producing their best work while staying on track with the publishing schedule. Pitches and first drafts can vary greatly in format and completeness. Some people like to create an outline for their first draft, others prefer to just start writing. The more you write, the more familiar you will get with your own writing process. What’s important is that you write multiple drafts and get feedback on them. This is how ideas turn into fully formed, thoughtful articles.

It’s important to have a publishing schedule so that we can deliver relevant content to our audience at relevant times. The editorial team strategically manages our publishing calendar to optimize article views and engagement. For example, if you are writing an article on Go and GopherCon is two months away, we can time the release of your article to coincide with other activity around the conference. This has the potential to bring more attention and readers to your post while the topic is trending.

Guidelines for contributing to Sourcegraph’s blog

Please follow these guidelines when contributing to Sourcegraph’s blog.

First, decide how you want to contribute:

Write the draft yourself

If you have an original article idea that you want to write, start by submitting your pitch via this Asana form so we can triage appropriately.

We interview you

If you are short on time or less comfortable writing, a member of the content team can interview you and use the transcript to start an outline for you to work from. Please mention if you want to go this route when you fill out your form.

Just submit an idea

If you have an idea to submit but you don’t want to write it, you can still submit the idea via the Asana form, just make a note that you are not proposing to write the post yourself.

Once you have submitted a pitch

  1. The Editorial team triages pitches weekly.
  2. An editor will be assigned and will give you feedback on your idea. At this point we may suggest an alternative channel or content format for your idea (guide/case study/social post/etc.)
  3. If the pitch is approved by you and your editor, next we’ll decide on a timeline together.
  4. First draft is submitted by the first draft deadline.
  5. An editor and/or peer reviewer is completed by the first draft review deadline. Please reference the peer review template when conducting your review. You do not need to answer every reflection question. This is a guide to help you provide useful and actionable feedback to the author.
  6. A second draft is submitted. This may be your final draft depending on its polish and completeness. If there are major outstanding structural and/or mechanical issues, your editor may request a third draft.
  7. The editor does a final copyedit.
  8. Once the final draft is approved by you and your editor, it will be staged and/or scheduled for release.

What happens if I want to write something on my own, on my own time for Sourcegraph’s blog?

Once you’re ready for an editor’s review, submit your draft in place of a pitch and follow the article submission guidelines. An editor will reach out to you with feedback, requested changes, and publishing options. Please note that immediate publishing may not be available. If you would like to publish on your own schedule, Medium is a great option for self-publishing.

What to write about for the Sourcegraph blog

Some questions to keep in mind when deciding what to write about in your blog post:

  • What’s in it for the reader? One of our Editorial principles is to have an audience-first mentality. What do we expect them to gain from reading the post?
  • Would someone share this? If you didn’t work for Sourcegraph, would you be interested in the post? Would you click on it on Hacker News or share it with your peers?

If you can answer both of these questions confidently, you’re on your way to a great post!

What makes a great engineering post?

Below are some common elements and themes found in the posts that tend to draw the most traffic and get the most attention.

  • Debugging stories: Take the reader on a winding journey with a satisfying conclusion. These often feel like a treasure hunt, with some twists and red herrings along the way.
  • Stories of building, scaling, implementing, and improving: A behind-the-scenes look at how the team approached a technical challenge. These are especially compelling if covering how we built or improved on a popular feature.
  • Hot takes: It’s not advisable to be controversial just for the sake of it, but taking an opinionated, contrary stance on a popular topic, backed by evidence and experience, will usually get people interested (more examples below).
  • Knowledge-sharing: Readers should be able to learn something from our blog that they can take away and apply to their own work.
Examples of great engineering posts

Below are some examples of the types of blog post that are usually popular (from our blog and beyond):

Themes

Dan Luu summarized some common themes from his own blog which could help spark some ideas for you too:

Brainstorm board

There are a lot of ideas on our Miro board. Feel free to use it for inspiration or let us know if you’d like to write about one of the topics! (Note: You may be asked to request access to the board if you don’t have Miro set up with your Sourcegraph email address yet.)

Blogs our devs trust

According to a question asked in Slack, our devs would trust the information coming from the following company blogs if they saw a post in a Google search or on HackerNews.

Learnings: TODO