Skip to content
This repository has been archived by the owner on May 31, 2024. It is now read-only.

Latest commit

 

History

History
86 lines (53 loc) · 4.73 KB

blog.md

File metadata and controls

86 lines (53 loc) · 4.73 KB

Incubator: Blog Style Guide

Incubator: Blog is a Developer driven content platform for hosting blog posts. When creating a blog post, as part of a developer Journey or a stand-alone resource, the content should attract and hold the attention of your reader. For a list of applicable topics, check out the section When to create an IBMCode Blog. IBMCode Blog posts are intended to be very light weight, and do not require any intervention from individuals on the IBMCode team.

Workflow

Resources

Create an Incubator Blog

  1. To create a new blog post, create a new Post in the IBMCode Wordpress console. The tone should be conversational, authentic, technical, and clear. The blog post should be written in the first person.
  2. Save the blog post as a Draft and enable Public Preview.

Publish an Incubator Blog

  1. Share the Public Preview link of your blog post with your manager or a subject matter expert to review the content for style and accuracy before publishing with Wordpress.

  2. Make any updates based on feedback. Change the blog post to Publish.

  3. Let folks know! Socialize it, post a link to Slack, let people know!

When to create an Incubator Blog

The following topics should be used for blog posts:

  • First time using new technology (Made my first Twitter bot)
  • Overcoming a technical challenge (Automating some task)
  • Comparisons (Bluemix vs Azure)
  • Opinions (Python is the best programming language)
  • Event promotions (KubeCon is coming up, see our speakers!)
  • Event recaps (Interconnect was awesome)
  • Announce new features (New Watson feature foo!)
  • History (Background on containers, from Solaris to Docker)

If your content is more technical, consider an Incubator How-To: https://github.com/IBM/incubator/labels/How-to

How to cross-post an Incubator Blog

Cross-posting blogs to other platforms such as Medium, or a personal site is encouraged as it builds your personal brand and eminence for the author. As a developer advocate, you should also ensure that your blogs are cross-posted to IBMCode. Always try to ensure your blog posts contains a snippet (at the top or bottom of the post) that redirects folks to the IBMCode blog. Here's an example:

This post is also available on [my personal blog][Medium][IBMCode] as [Title of the blog]. Check out IBM's developer advocacy effort at IBMCode for our latest Developer Journeys, engage with our Developer Advocacy team to create new skills in your organization, or find an event near you.

List of approved sites to cross-post to

If you'd like to add to this list, propose a change to this document!

Writing Style

  • Include a scenario to help provide context and create interest. For example:

Imagine you are developing a mobile application and face these common pitfalls [examples]. With the [applicable application], you will not only solve this [common problem] but also [get some other benefit].

  • Have at least one image, such as a screen shot

  • Lists are great for grabbing a readers’ attention.

  • The site automatically truncates the first 340 characters (approximately 55 words) of the blog post as the meta description. This means you have 340 characters to grab your readers from this meta description.

  • Aim to make your blog around 1000 words in length.

  • Use inline links to other web pages to help provide background and context.

Wordpress Formatting

  • Create subtitles: wrap the text with <h2> and </h2> or <h3> or <h4>
  • Extra spacing between paragraphs: just add <br> between the paragraphs
  • Code blocks: wrap the text with <pre> and </pre>
  • Render text as "syntax": wrap it with <code> and </code>

Examples

The following are great blog posts that can be used to base your next blog post on: