Developers often ask an Information Developer to edit a blog that they have written and placed in the https://github.com/rackerlabs/docs-developer-blog repository. Blogs in this repository are published to the Rackspace Developer Blog site at https://developer.rackspace.com/blog/.
When you write a blog, use the writing guidelines in this Style Guide as you would with other documentation that is curated by the Information Development team. Start with the information in the Quickstart.
This topic provides additional guidelines specific to writing blogs for the Rackspace Developer Blog site.
Things to consider before writing a blog#
Before you start writing, consider the following questions:
- What is the goal of this developer blog? Describe it in two sentences or
- Is it to be helpful and answer a question or offer how-to information?
- Is it to provide “thought leadership” or show our expertise in an area? If so, describe what you’d like to convey.
- Is it something else altogether? If so, what? It’s possible that your idea might be better presented as an article on the How-To support site at https://support.rackspace.com/ or as a blog with a marketing flavor published at https://blog.rackspace.com/.
- What is the significance of the content of the blog? Is it how to use a new offering? How is it helpful to customers? Does it frame our expertise is a new way?
- Explain how the content of the blog aligns with, supports, or strengthens Rackspace’s current business priorities and strategy.
- Who is the target audience for this blog?
- What specific customer problems or pain points does the blog address? Provide names of customers willing to be references in support of the post.
- Does the blog describe how to use something that Rackspace provides that it does better than the competition or that no other competitor offers? Does the blog provide quantifiable and defensible information (such as performance metrics) showing the Rackspace edge over the competition? If yes, explain.
Blog writing suggestions#
When you write your content, we recommend the following rules of thumb:
Length: Rackspace blog posts generally run between 500-1,000 words, but let the content be your guide. Take the space you need to tell your story, but don’t pad it unnecessarily. Going long is okay, too, as long as it’s worth reading.
Tools: Use the word processor or text editor of your choice to write the blog.
- An attention-grabbing opening, known in the news business as a “lede”
- A “nut graf” - a sentence or two letting readers know what you’re going to be talking about and why it matters
- Some background information or context, such as the history of a product
- A conclusion (and a call to action, if appropriate) with links and contact information
Consistency: Be as consistent as possible in style with other blogs on the Rackspace Developer Blog site.
Bullet points: Bullet points are useful for listing features.
- Images should directly support or illustrate blog content. Examples include a screen shot, diagram, or table that illustrates the concept or technique that is being described.
- Any image pulled from another source should provide a reference to the source directly underneath the image.
- Add social media icons with their links for twitter, Facebook, and LinkedIn at the bottom of the blog post. (Information Development provides a template for this that you can add to your blog.)
Reference section: If your content uses a lot of content from another source, provide a Reference section at the bottom of the blog post with a link to the reference.
Think “be helpful” rather than trying to sell a product or service. What does the product do? How does it help the customer?
Write a good lede: When crafting your lede, consider how the information in your post helps customers. An announcement of a new product is not a lede, but that product’s money-saving capacity may well be one. For example:
Not good: Today Rackspace is pleased to announce the release of four new features in Office 365.
Good: Increased storage, security, and cost-saving measures are now available to enhance the already-robust Office 365 suite available from Rackspace, making it even more attractive to a wider variety of business users.
Stay focused on your topic: If you find yourself straying, you may have enough material for a series. It’s okay to break up a big topic into more digestible bites. Formulas like How to, Top 5 or 10, and curated lists tend to do well.
Show don’t tell. Can you create a graphic or image, or add a screen shot to illustrate your point?
Avoid jargon. Rackers (and the entire tech industry) tend to speak in jargon. Unless your post is aimed at a technical audience, use plain English. There is never a reason to use business jargon.
Link link link: A first product mention? Link to the product page. Outside accolades? Link to it. Citing a study or source or article? Link to it. Have we written about it before? Link to it. Mention a partner or customer? Link to their site.
Keep it concise: The Internet has shrunken everyone’s attention span. Say it once, say it well. No need to repeat the same information in different format. Similarly, keep paragraphs short. Long blocks of text are intimidating. Use concrete examples whenever possible. If you get stuck, don’t fret. Just send your draft to the blog team. We’re here to help.
Voice and tone#
Use these guidelines to write a blog that is friendly, helpful, and inspires confidence.
The primary job of the words in a blog is to help users complete tasks with no confusion and minimal interruption. However, the voice and tone that we use with words also influence how people think and feel about Rackspace.
Voice is our style, and communicates our personality to the user. Tone is our mood, and communicates our attitude about the subject to the user.
The words we choose, and the ways we use them, should reflect our goals: building trust, inspiring confidence, making things easier, and developing a relationship with Rackspace users.
When you write blog text, use words that reflect the following attributes:
Consider the following best practices for voice and tone when you write blog text:
- Write in a way that the user wants to be spoken to. Use helpful words and phrases that are informative, simple, clear, and easy to understand.
- Temper the enthusiasm conveyed in confirmation messages.
- Be careful about laying blame. Don’t take the blame for a negative situation. Don’t lay the blame of the negative situation on the user.
- In positive situations, be encouraging and offer next steps. Don’t take credit for the user’s success.
- In negative situations, be clear about the problem and how the user can fix it. Don’t ask the user to trust us without providing more information.
Write to the user by using second person and imperative mood#
Users are more engaged with content when it talks to them directly. You talk to users directly by using second person, addressing the user as you. Second person also promotes a friendly tone. For more information, see Write to the user by using second person and imperative mood.
The following guidelines for writing to the user apply specifically to the Rackspace developer blogs:
- For blogs, use the first-person singular pronoun I only when authors of blogs are describing their own actions or opinions.
- Switching person (point of view) is acceptable in blog posts that use first-person singular but then switch to second person for instructional steps.