Part copy editing, part technical writing and part training, creating good user guides may be one of the hardest kinds of writing. Creating a user guide that works for anyone – no matter their technical skills – and presenting that content in an elearning or online environment is even harder.

It’s what I’ve been trying the past year or so. The question of course is: what have I learnt from that?

Simple 1, 2, 3

Recently, I’ve been looking into new ways to present this kind of content. In itself, that’s not hard. You describe simple steps in the simplest way: click here, go there, do that.

In practice though, things are not that easy, and there’s a lot to take into account, such as terminology and consistency. Also, using numbering or bullets, evidently seems the way to go, but what do you number? Every action, every click? And speaking of: what exactly is an action?

Also, think of what a tutorial should look like. Type, spacing, indenting… The way you design a manual makes up for half its efficiency as well.

Click that thing

Say you’d have to explain someone how to open a simple app, such as MS Office’s Excel.

As soon as you try for yourself, you’ll notice that there are lots of ways to do that. The question is: which one is standard, which one is the simplest?

Moreover: how do you put into words things like ‘go there with your mouse’?

Or something like:

start typing the first letters of the app’s name or a part of its name and wait a bit because your search box will automatically suggest a number of possibilities and the more you type, the shorter that list becomes so it’s easy for you to make your choice and, oh, making your choice can be done either by clicking or hitting enter…

See? Definitely not that easy.

My Way?

For now, I’m using the simplest method I can think of, like here for opening that app:

But I wonder how this would pan out when trying to describe distribution lists or pivot tables?

Or the Apple Way?

While researching this, though, I came up with one of the best manuals I’ve seen in a while. Accuse me of fanboism all you like, but evidently it’s from an Apple user’s guide, in this case iWork.

Luckily, all our courses have screenshots and screencasts as well. But that doesn’t mean the procedural bit shouldn’t work either – and work at its simplest and its best.

Have you ever written or tried writing any of these? What’s the best/worst manual you’ve ever seen? Links and screenshots would be welcomed.