5 Steps to Improving Your Software Documentation

Overview

Software documentation can be the bane of a software developer’s existence. It is the least interesting part of the development process. Since most people don’t read the documentation anyways, why bother?

The truth is that users will read your documentation if you fulfill two requirements:

  1. Give the user what they want (the right content)
  2. Give them that content when and where they want it (the right delivery format)

What the user wants

Remember this important truism: Documentation isn’t read, it is referenced. Your users aren’t going to cuddle up by the fire and read your software manual. They are going to read it when they get “stuck” using your software. They are going to read it when they have a question. Make sure that your documentation makes it easy for them to find the answers to their questions.

When and where they want it

You may think that if a user calls or emails support that it is too late to get them to use your documentation. Au contraire. This is the perfect time to deliver your documentation. Your user has a question. Your documentation has the answer. You just need to make sure that you can deliver it to them in that support situation. Guess what, a 100 page PDF file isn’t going to work. You are going to have to come up with a new delivery format to make sure that you can deliver exactly the content your user needs when they contact support.

The Methodology

Here is a very simple methodology to follow that is guaranteed to give you instant results. It doesn’t take any special training and requires much less work and delivers better business results than any other documentation method we are aware of.

  1. Scope Out Your Documentation

    Before starting to write your documentation you need to plan what you are going to write. This should take all of 10 minutes. DON’T GO THROUGH YOUR APPLICATION SCREEN BY SCREEN. This is the worst possible approach. It isn’t how your users think. They don’t care about screens. They care about completing tasks. So base your documentation around tasks, not features.

    To make this easier, just write down actual questions your users have. Most likely they aren’t asking, “What is the Account Preferences tab”. Their questions are more likely to be something like “How do I configure my account to export a document?” The questions you write here should be “How do I” questions. You may have a few “What is this” questions as well, but those should be far outnumbered by the “How do I” questions.

    Don’t take too long here. You can always add more later. We often suggest that people just write down the 10 most common questions. If all you do is answer those 10 questions then you will dramatically decrease your support requests. Your documentation doesn’t have to be complete. You can add more to it later.

  2. Fill in the Answers

    Now go back and fill in the answers. Don’t add too much detail. Go for clarity over completeness. Each question should be answered with a step by step description of what it takes to accomplish the task. Don’t add too many caveats either. 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 sections in your documentation that cover each one of those scenarios then to try to lump them into one section.

  3. Add Images

    There is nothing that will improve your documentation more than adding screen capture images. Adding screen captures helps you communicate information more clearly and more quickly. But don’t just put up a single screen capture for each section. Add an image for every step of the process.

    There are a lot of options for getting images into your documentation. You can use free system utilities on both Mac and Windows or choose from a wide variety of commercial applications. We even make a pretty good screen capture application that will help you turn your screen captures into great documentation.

    Whatever tool you use, make sure you add images to your documentation. Trust us, your users will love it and your support requests will plummet.

  4. Choose the Right Delivery Format

    You should be able to deliver your documentation via the web. Remember where your customers want to access this information. It is during a customer support interaction via phone, email, forums, Twitter or some other means of communication. That means you need to be able to send a url to your user that points directly to the answer they need. If your documentation is locked inside a 100 page PDF then this won’t be possible. Each one of the questions that you listed when you started this process should be its own web page with a unique url. That way you can point your customer directly to the answer they need. You can look at our manual for a good example.

    You may choose to also deliver a PDF version of your documentation. That is fine. But at the very least you need a web version of your documentation.

  5. Keep it Up to Date

    Outdated documentation is worse than worthless. It actually hurts your organization. When a user encounters documentation that is out of date they stop trusting your documentation. That means they won’t reference it anymore and your support requests are going to increase. Make sure you establish a process for updating your documentation that is easy enough that you will actually do it.

    The fact that you have structured your manual around questions that users ask will make this much easier. If a section of your software gets changed it is usually pretty easy to see which questions have been affected. If you have added images this is even easier. All you have to do is quickly scan the individual sections of your documentation to see if there are pictures that are out of date.

    Having the right tools can make keeping your documentation up to date much easier. Some options include:

    1. Automating a process for outputting and uploading HTML help files to your server (this can be combined with programs like ScreenSteps)
    2. Using a wiki that can be authored via a web interface
    3. Using ScreenSteps Live, our hosted documentation service that has been designed around this methodology.

That is all there is to it. Put these tips into place and you will quickly be creating documentation that gets used by your customer and helps you decrease your support requests.

Learn More

Want to learn more about creating great software documentation that your customers will love?