Seven New Tips for Writing User Documentation

This article lists useful new tips on how to write User Documentation.

Let me start by saying that writing good instructions is not simple. It takes time, it takes subject expertise, a good understanding of the audience, and writing skill. I’m not going to re-cover those things here as there are plenty of those articles on the internet covering off those topics.

So, assuming all of the above is in place, here are some tips that might help make even better User Documentation.

Use full screenshots.

Ever wondered if the instructions you’re reading are actually for the application in front of you? I have.

Including the full screenshot can improve the visual understanding of the content being explained. 

Not only can the user be confident they’re on the right screen in the right application, but you can guide them directly to the button or other control.

Having said all that, although you should use full size screenshots, the screen that you grab does not have to fill the whole monitor. If your monitor is say, 1920 pixels wide, you might just position your application window in the middle of the monitor at 1200 pixels wide (you don’t need to measure it, just make it smaller than the full window).

I use the Windows snipping tool, set on Windows Snip model to grab screens. SHIFT-WINDOWSKEY-S is your shortcut.

Use sequenced steps.

Like cooking, assembly of furniture, whatever, procedures in software are about doing things in a certain order.

Using numbers on the screenshot is a simple way to mimic real world explanation of how to do something. Numbers guide the eye, make the path clear, and stop things getting missed.

We have our way of doing this at Runthru (see Runthru Instruction numbering) but you can manually add numbers in other ways of course.

Bottom line is that you will do your readers a big favour by guiding them with numbers.

Let the pictures do the talking.

This one really depends on your audience, and your writing style. Sometimes, you can cut corners because you’re using full size screenshots. Sometimes you can say ‘check the boxes exactly as shown here’ or ‘fill in the fields as shown here’. This can save time in creation without losing any quality in the output. As I said, this isn’t for every occasion, but for some documentation it can be a real time saver.

Make sure the screenshot and the words are consistent.

The picture and the words must say the same thing. Doing otherwise is asking for trouble. The reader of your document is time poor. If the procedure says to check boxes and picture doesn’t mirror the words, you are asking for trouble. It seems so simple, but I’ve seen plenty of examples where the two sides of the same information are in conflict.

Teach the one key path.

If there are two or more ways to do something, explain one of them in your document. There are plenty who would disagree with me on this but here’s the rationale. You have too much stuff to write already.

Using valuable time filling up a single work instruction with the alternate ways of achieving the same thing might be fulfilling but it’s probably not worth the effort.

My bet is that you have more documents to write and update than you have time available, so my suggestion is to supress any perfectionistic traits you might have and move onto the next procedure on the list.

Your world will benefit more from having more documents on the shelf, than having fewer documents that explain multiple ways to achieve the same thing.

Teach one topic per document.

This might be obvious, but just in case. In general, shorter, more targeted documents are easier to consume.

Big documents containing multiple procedures might seem like a good idea (there was some historical benefits to having one bound manual) but in general, multiple contents in one single big document tends to confuse users. Documents with targeted content that address specific topic is generally easier to find and to consume, even it means you have more documents.

You don’t have to explain every click.

When dropdown boxes were new, you would have to explain the need to click the dropdown arrow, then scroll, then find the item in the list and click on it. You would be hard pressed to argue that that’s still necessary. It’s generally just fine to say ‘select the required option’.

On a similar theme, why not say ‘fill in the address fields’ instead of going through each option one by one.

In closing

I hope this was of some use to you. We make software that makes capturing and sharing how-to information so much easier. Please have a look at https://www.runthru.com