How to write a great roadblock article

Here at Blue Mango, we talk about two types of help articles:

  1. Those designed to remove roadblocks for your customers, and
  2. Those designed to provide a road map for your customers

This article focuses on the first type, and will teach you how to create awesome "roadblock" articles. Read more about roadblocks and road maps.

The steps to writing great roadblock articles are:

  1. Create a great title
  2. Answer the question with screenshots
  3. Add a header for each screenshot
  4. Add instructional text (if needed)
  5. Publish it

Following these steps will help you approach your documentation in an organized way and allow for you to create a lot of quality “roadblock” articles in very little time.

Create a great title

If you create a great title for your article, then the article will practically write itself. So, what should your title look like? Simple. It should be the specific question that your article is going to answer. In fact, the more specific the question, the better.

Here are some examples of bad titles:

  • Accounts screen
  • Users overview
  • How to work with documents

These titles don't answer specific questions and are too general to be helpful. The goal of your article is to remove a specific roadblock that your customer has run into.

Here are some examples of good titles:

  • How do I create an account?
  • How do I delete a user?
  • How do I edit a document?

Each of these titles is specific, focused, and will help you write a relevant article that removes your customers’ roadblocks.

Answer the question with screenshots

Answer the question in the title by capturing a screenshot of each step of the answer. For example, if your title were "How do I create a user?"  you would capture an image for each step of the process required for creating a user.

 

Why capture the images first?

A lot of people think that it is best to write down the steps first, before capturing the images. In our experience, those people would be wrong. Why? Because text lies - images don't. When you are writing out steps you can write anything you want, but the steps you are writing may not actually work. We see this happen all of the time. The author thinks that they know all of the steps involved, writes them out in a list,  discovers that things don't work exactly how they expected, and then they have to go back and change their list.

By capturing the images first, you will know that you have documented all of the steps without leaving anything out. Text can tell lies. Images can't. Capture your images first. A tool like ScreenSteps can make this very simple.

Add a header for each screenshot

Now go back and add a header above each image you have captured. Headers might look like:

  • Select the users menu
  • Select "New user"
  • Enter user information

Although headers may seem unnecessary to you, your customers will appreciate the additional clarification.

Add instructional text

Add additional instructional text if necessary. Don't add too much though. The goal is to help the customer accomplish the task. If you put in too much detail then you may just confuse them. Only write what is necessary to help them get past the roadblock. If you want to provide additional information, create another article and reference it in your roadblock article.

 

Tip: Avoid caveats

Caveats in your documentation are areas where you say, “If you want this output then do this, but if you want this other output then do that, unless of course you want this other output then do this other thing.” Your user will instantly be lost. It is better to create separate articles that cover each one of those scenarios than to try to lump them into one article.

Publish it!

Publish your article and send it to your customer. They will let you know right away if the instructions worked or not.