5 Keys to Creating Docs that Rock


We here at Blue Mango, see a lot of software documentation. Not only do we create a ton of documentation, but we also regularly work with customers to help them devise strategies for creating, distributing and updating their documentation.

Through our years of experience we have come up with 5 keys that will make or break your documentation efforts. But before we get into the details of the 5 keys you need to know what we value in documentation.

First off, we don’t care about XML, single sourcing, approval processes, stylistic consistency or revision tracking. We judge documentation on two criteria:

  1. Does it help the customer?
  2. Does it help the business?

Everything else is secondary. If your documentation doesn’t help your customers and your business then you shouldn’t waste your time writing it.

So, if you are looking for ways to outsource your documentation, or for the cheapest way to get your documentation done, then you might want to move along. These 5 keys probably won’t help you. But if you care about your customers, you care about communicating clearly and you care about improving the way you run your business, then these 5 keys should help you out.

1. The Goldilocks principle

Wikipedia describes the Goldilocks principle like this: “The Goldilocks Principle states that something must fall within certain margins, as opposed to reaching extremes.”

We see a lot of documentation that goes to extremes. One extreme is the app developer who believes that their app is so simple that they don’t provide any documentation at all. The other extreme is the organization that feels like they need to teach you the history of their application going back to the early 1600’s for you to be able to accomplish anything.

In reality, your documentation should give your user just enough information to accomplish their task and nothing more.

2. Think like a GPS

How does a GPS work? It figures out where you are and where you want to go, and it takes you there. It’s awesome! Documentation should be the same way. You need a way of delivering exactly the instructions a customer needs to help them reach their desired destination.

Delivering an atlas to your customer when they are stuck isn’t going to help them get anywhere very quickly.

3. Attach with velcro, not cement

The PDF manual. A wonderful tool that has been abused. We see so many organizations that are delivering 100+ page PDF manuals. When a customer asks you a question on Twitter, how is a PDF manual going to be useful? Or what if you have lengthy web pages with all of your documentation on the same page? Or worse yet, what if you use one of those awful help authoring tools that delivers all of your help in frames with the same URL for all of them?

If any of this sounds like your documentation, then we have bad news. Your documentation is attached with cement. You need to create documentation that is attached with velcro so that you can easily pull out exactly the information your customer needs and point them to it.

4. Pictures speak louder than words

I was reading a discussion online once. It was between a bunch of technical writers. They said screenshots should only be used very sparingly. They claimed that the text descriptions they wrote worked just as well or better than having pictures.

If you believe that then I have bridge to sell you.

You shouldn’t just use screenshots and pictures in all of your documentation, you should go totally crazy with screenshots. Screenshots add clarity, reduce confusion and help your customers. If you find that your help authoring tool makes it hard to add screenshots and images to your documentation, then get a better tool. But don’t leave the pictures out.

5. Do it, don't finish it

Do you think of your documentation as a project? How long does it take you to finish it? A week? A month? Longer?

Do you think of customer communication in the same way? Do you work on communicating with your customers for a few weeks then stop and say nothing for 6 months to a year? Documentation is a communications tool. It can’t be something you finish because as long as your customers have new questions, as long as your product is changing and evolving, as long as you need to communicate with your customers you will need to create and update your documentation.

Documentation is something you do. It isn’t something you finish.

About Us

We create ScreenSteps Live to help organizations create beautiful documentation without developers.

Learn about ScreenSteps Live »