Blogging Your Open Source Projects

The Yahoo Open Source Program Office (OSPO) provides services to help engineers at Yahoo prepare code for external publication, promote projects, and build open source communities. If you are interested in open source collaboration, we are here to help. To get an overview of our program, vist the OSPO Welcome Page intranet page, chat with us on our internal Slack channel (#opensource), or send an email to ospo@.

This page highlights how the OSPO helps you promote your project using blogs and podcasts.

Step Zero: Planning for Success

Yahoo hosts a tech blog called the Yahoo Developer Network blog. We invite all tech content from any engineering group to publish technical content to this blog. After you publish your blog post, the OSPO promotes it internally and externally.

Did You Say Podcasts?

For many people, podcasting is a more engaging way to share and consume content than blog posts. Yahoo hosts a podcast called the Dash Open. We share our episodes on Apple Podcasts, Soundcloud and Spotify.

Our podcasts follow a simple conversational style where the host prompts the guest(s) to describe the project they are working on or to share some message for the listeners. We edit the conversation to get to about 5-10 minutes of content. We transcribe the podcast to text for three reasons:

Accessibility. We know podcasts are great, but not everybody hears. We want all people to have access to our content.
Convenience. Even those of us who hear sometimes prefer to read a podcast; like when we’re in the office and don’t have our earbuds handy.
Indexing. As we get more episodes, we expect people to search for a conversation. It’s a lot easier to index text for the search engine.

If you record a podcast with us, we’ll promote it by pointing to our Dash Open website so that it points to the version with full transcripts. You can think of a podcast as a form of a blog post. When you think of a blog post, please consider the following steps we’ll take to make your post a reality.

Step 1: Consider the Reader

Many of our blog posts announce new open source projects. Before you start writing anything, answer these questions:

Who is the audience for this post?
What makes your project interesting to others?
What can we say about this code in production?
How should readers get started using your code?
What do you want this code to do in the future?

Step 2: Tell a Good Story

A good blog post tells people we did something we think they should notice.

A good blog post is clear about the audience it’s addressing. If someone in your intended audience sees the post, they know if they should read it. If someone is not your intended audience, they know to skip it.
The post starts with the main announcement: That we published something new and want to tell you about it. Don’t bury the lede in a long story explaining how you got to the solution. Start with the news. You can then develop the story in the body of the blog post.
You don’t need to include everything a reader needs to know about your project. Write an invitation to learn more. The goal of the blog post is to get people to visit the project and try it out and hopefully tell others about it, not to be the project documentation.
Blogs are more than words. Include an architecture or dependency diagram. Add a graph showing how things improve when people use your project.

Step 3: Get to the Point

Blot posts should be 750-1000 words. If you need more than 1000 words, consider creating a blog series with a few related posts.

Step 4: Review

Before we publish your blog post, you have to get approval from your manager, PR, and the OSPO.

Share your blog draft with the OSPO and we’ll create an approval list that is appropriate for your blog topic. Each group will review the text and indicate their approval. We’ll then schedule the publication on our publication calendar, post the blog and promote it internally and externally.

Step 5: Attribution Considerations

Much like open source code, we give proper attribution to content. Our blog posts contain text and images we create and own or licensed to use for this purpose (e.g. permissive Creative Commons licensed images).

Much like open source communities, we take special care to make sure that we treat people’s personal images and information in accordance with their personal wishes. If your post contains a picture of an event, we need to get permission from everyone in the photo before posting it. If you are naming people in the post, we need their consent. When seeking consent, ask if they want their name linked to their LinkedIn profile or Twitter handle. We need a special release form signed if the person is a minor.