Blog guidelines#

Developers often ask an Information Developer to edit a blog post that they wrote and pushed to the https://github.com/rackerlabs/docs-developer-blog repository. Posts in this repository are published to the Rackspace Expert Insights Blog site at https://developer.rackspace.com/blog/.

When you write a post, 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 posts for the Rackspace Expert Insights Blog site.

Things to consider before writing a blog post#

Before you start writing, consider the following questions:

  • What is the goal of this Expert Insights post? Describe it in two sentences or less.

    • 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. If it’s less technical, consider sunbmitting it to the Solve blog, published at https://www.rackspace.com/solve.

    • 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 post with a marketing flavor published at https://blog.rackspace.com/.

  • What is the significance of the content of the post? 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 post aligns with, supports, or strengthens Rackspace’s current business priorities and strategy.

  • Who is the target audience for this post?

  • What specific customer problems or pain points does the post address? Provide names of customers willing to be references in support of the post.

  • Does the post describe how to use something that Rackspace provides that it does better than the competition or that no other competitor offers? Does the post provide quantifiable and defensible information (such as performance metrics) showing the Rackspace edge over the competition? If yes, explain.

Blog post 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. We can also convert a single post to a series, if necessary.

  • Tools: Use the word processor or text editor of your choice to write the blog.

  • General format:

    • 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 posts on the Rackspace Expert Insights Blog site.

  • Bullet points: Bullet points are useful for listing features.

  • Images:

    • Images should directly support or illustrate post 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 post.)

  • 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.

  • Be helpful: 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 might 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 might 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 specialized, 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 post that is friendly, helpful, and inspires confidence.

The primary job of the words in a post 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 post text, use words that reflect the following attributes:

  • Human

  • Trustworthy

  • Knowledgeable

  • Accurate

  • Professional

  • Approachable

  • Helpful

Consider the following best practices for voice and tone when you write blog post 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 Expert Insight blog posts:

  • For posts, use the first-person singular pronoun I only when authors of posts 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.

Plagiarism: Understand and avoid it#

Plagiarism is stealing someone else’s words and presenting them as your own without giving credit to the author. Suppose your boss asked you to paint a picture of a cat, and you gave him a cat picture created by someone else. That’s wrong, right? Maybe if the boss just needed any cat painting, it would be ok, as long as you told him that Bob Smith painted it (and hopefully you bought it or have Bob’s permission to use it). However, if your boss needed to see your painting, perhaps to evaluate your skill, then passing Bob’s work off as your own is theft and deceit, plain and simple.

One way to think of it: Never copy and paste (or type in) someone else’s brilliant text without saying where the words came from.

Another consideration: In your blog post, you communicate something you know about and care about. The topic is important to you. Knowing the information in your post helps you do your job, helps others, explains complex topics, and so on. So, share that information in your own words from your own experience.

So, how do you avoid plagiarism? Give credit to your source in one of the following ways:

  1. Directly quote your unnamed source. For example: According to the Oracle BI Enterprise Edition (https://www.oracle.com/business-analytics/business-intelligence/technologies/bi-enterprise-edition.html): “Oracle Business Intelligence 12c is a unique platform that enables customers to uncover new insights and make faster, more informed business decisions by offering agile visual analytics and self-service discovery together with best-in-class enterprise analytics.”

  2. Directly quote a named source. For example: Rittman Mead explains the problem in his post (https://www.rittmanmead.com/blog/2018/11/where-are-my-users-coming-from-analysing-obiee-connections-methods/): “But one day you start noticing new BI tools appearing in your company that provide similar KPIs to the ones you are already exposing and you start questioning where those data are coming from.”

  3. Paraphrase the source (named or unnamed). For example: Rittman Read (https://www.rittmanmead.com/blog/2018/11/where-are-my-users-coming-from-analysing-obiee-connections-methods/) talks about how new BI tools with KPIs like yours just show up, and you can’t identify the data source.

Here’s another example of avoiding plagiarism. This source (https://www.easybib.com/guides/plagiarism-guide/how-to-avoid-accidental-plagiarism/) yielded the following nugget: “Remember, your paper is an example of your writing, so you should be expressing your original thoughts, not just repeating published ideas. Outside sources are there for you to learn more about your topic and to provide evidence to your claim only. By writing a completely original first draft, you will ensure that your paper is a reflection of your own hard work.” (See? credited and linked source and quoted text!)

In other words, if your post is nothing but a collection of quotes and paraphrases from other sources with nothing of your own expertise and experience, another topic might suit you better.

But what if, although you know your topic in-depth, you just aren’t that good with words? Or English is your second or even third language? In that case, you might think pulling all those quotes (and giving proper credit) would be appropriate. Well, kind of, but here’s an even better option. A blog post is generally a more casual or conversation piece, not intended to be an example of perfect scholarly erudition for the ages. So, while expert content is critcal, perfect English isn’t necessarily required in the submission draft. Also, your blog editor is here to help! Editors love tweaking and polishing words so the readers can get exactly what they need from the post without the distraction of imperfect grammar or usage. So, send in your words and thoughts, and let the editors work their magic.