Way back in the days when dinosaurs and unicorns roamed the earth, not many people owned what we now recognize as a Home Computer. And even those people that did own a Home Computer, it was a command-line-based system that did not have buttons, menus, drop-down lists, and the myriad of other interface tools that we take for granted today.
But now if you hop into the WABAC machine with Mister Peabody and Sherman, we’ll leap forward 30 years to the present day. The dinosaurs and unicorns are still here, but they’re wired to the teeth (and horns) with portable computers and cellphones that have more computing power than the systems that put Mr. Armstrong on the moon.
The point of all this dizzying time travel is that the modern computer user understands the concepts of menus, mice, buttons, and listboxes. This means that we sidestep the explanation of how to use these interface tools, putting the focus on the product instead.
For example, the old way of explaining how to select a command from a menu might have looked like this (yes, including the graphics):
1. Open the View menu. The following commands appear:
2. Open the Explorer Bar submenu. The following commands appear:
3. From the Explorer menu, select Tip of the Day.
All this extra information is not needed by the modern reader, making the procedure heavy and overly-wordy. If you can safely assume that the reader knows how to open a menu, you can shorten the above procedure to single step:
1. From the View menu, select Explorer Bar > Tip of the Day.
or
1. Select View > Explorer Bar > Tip of the Day.
Using the brackets, you can drastically shorten a procedure, provide a clear path to the command(s), and accelerate learning. A shorter procedure is less intimidating to a novice user and less annoying to a technically-minded user, making the technical document easier to use and allows the reader to return to the tool quickly and efficiently.
Of course, you can take this philosophy too far and make your procedures so short that only an advanced user would understand them. This is why audience analysis is so critical to determining the level of information to include in the technical documentation. Find out what they know already, determine what they need to accomplish, and teach them how to use the tool.
In performing your audience analysis, talk to the people who know the audience, not the tool. Interview the trainers, the product designers, the sales people, and the support people. I would recommend that you do NOT speak to the programmers/engineers for this type of information. The programmers/engineers tend to know how the individual parts work, but they don’t understand how the tool works as a whole, and they don’t need to know how a user will work with it. There are exceptions to this generalization, but by and large, the programmers/engineers are too immersed in the tool itself to be objective enough to evaluate the level of explanation needed to a person who has never used it.
