Blue Mango

How to Create Killer Documentation

Get rid of projects, establish a process

Forget about pointless planning sessions and establish a process that lets you create "just in time" documentation.

Too many people think of software documentation as a project they will complete as opposed to a process they will establish. Software documentation projects almost always fail. They fail to meet the real needs of users. They fail to provide up-to-date information. They fail to deliver real business results.

The key to creating great docs is to abandon projects and instead establish a documentation process.

I explain the details of how you can accomplish this in the short video below. The tips I share in this video are what our most successful customers use to make software documentation a key part of their business strategy.

The process

Here is the simple process that helps you know exactly what to document and when to do it:

Write down real questions

Answer them

Publish the answers

Use the answer (send the url to the answer to the person who asked the question)

Rinse and repeat

Step 1: Write down real user questions

The first step is to write down real user questions. Why? By answering real user question you know that your documentation will be useful because they answer a real question, not one you made up.

Step 2: Answer it clearly

Create a help article with the question as the title. Then write an article that answers that question, and only that question, clearly. We suggest using a lot of screenshots and visuals to make the answer crystal clear.

Step 3: Publish it to the web

Publish your article to the web. It should not just be a section of a larger page but should have its own unique url.

Step 4: Use it

Send the url to the answer to the person who asked the question. When that question comes into your support desk again, send the url to that lesson as your response. You will be able to answer questions more quickly and your users will be excited to get a clear responses with pictures as opposed to a text-based email.

Step 5: Rinse and repeat

When a new question comes in, check your online knowledge base.

Does it have the answer? Then send it as the response.

The answer doesn't exist yet? Create it, publish it and send it.

Adapting this approach for internal process documentation

You may say, but I'm not running a support desk, how do I know what to document? Take a new employee and have them get started on a new responsibility. Write down all of the questions they have when you help them get started. Now go back and create help articles that answer each question. You will quickly have documentation that can be used by any of your other employees to accomplish the same task.