Blue Mango

How to Create Killer Documentation

Control the scope and detail of your documentation articles

By limiting the scope of each help article you write you will create documentation that is:

Easier to understand

Easier to author

Easier to keep up-to-date

Easier to use in support situations

The biggest mistake we see companies making when authoring their documentation is misunderstanding the relationship between scope and detail in their help articles. They are violating the Goldilocks principle. They either deliver too much information or not enough.

If your readers feel like the guy in the video below then you know that you have a scope and detail problem in your documentation.

When you add too much detail to an article you decrease the reader's ability to understand and apply the information you are trying to communicate. The ideal approach is to create many small articles, with varying amounts of scope and detail.

This next video explains the proper relationship between scope and detail.

Video: Getting the Scope and Detail Right

Balance scope and detail and you will create better help articles

If you are going to write an article that is very broad in scope, limit the detail you include. If you are going to write a highly detailed article then limit the scope.

Here is an example:

If I were writing the help files for Google Analytics I would write many small articles. One of those articles might be titled, "Using Goals." In that article I would limit the amount of detail I would include. I would try to focus on a broad overview of goals and not include every detail you need to set up and use goals.

I would then follow up with more specific articles:

How to create a goal

How to create a goal that tracks revenue

How to create a dynamic goal

How to view goals in reports

Each article would be fairly short and would strike a good balance between scope and detail.

For each article you write, focus on this balance of scope and detail. If you are going to write a high-detail article then limit its scope. If you are going to write an article with a broad scope then limit the detail.