Pure reference documentation is like a map. It sets out the facts about the system. We expect the facts to be true, and clearly expressed. That’s all we are really looking for.

Moving up a level, we get a “journey”. A journey goes through the system in a certain order, looking at each component as we go. We expect it to express the facts, but to present them in a logical order. We want to read the book from start to finish, and learn about the system. Guidebooks are useful, guided tours are useful. If you don’t know an area they are much more useful than maps.

The next and best level is the adventure. This is where you throw yourself into the location, try to achieve something, and document how it goes. A great tutorial takes its reader on an adventure in the system. Facts and clarity are still important – but even more important are actions, incidents, challenges, and results.

When you’re planning a tutorial on any piece of software or topic, ask yourself… “what adventures can we have with this?” It’s the adventure that will keep readers interested and learning. They’ll pick up the facts as they go along.

It’s your choice. Maps and journeys are useful. Adventures are inspiring.