July 28, 2007

How to Write Excellent Online Instructions

Posted in Featured, Instructions, Web, Writing at 01:08 by Mattias

Online instructions can be a lot of things – tutorials, FAQs, troubleshooting manuals or user guides. Depending on the quality, they can be lifesavers or sources of major frustrations. These tips will help you write instructions that provides a better user experience for your users, which will save both them and you a lot of time and trouble.

Encourage action. Use active, imperative sentences (like this one!).

Be brief and to the point.

Use headers and make your instructions easy to follow.

Explain the concept behind the action only if the user needs to form a mental model to make things easier for her. Don’t explain the entire background for the action. Don’t get too technical, provide non-intrusive links to technical discussions if they still might be of interest to some users. Your users are reading your instruction to solve a problem or to complete an action. They primarily want to know how, not why.

Take advantage of the capabilities of the online medium. If the content is too advanced, split it off behind a link. Utilize video, illustrations, and hands-on, try-it-out guides where appropriate. Just remember that the users who might need your instructions the most might not have access to Flash or broadband connections.

Tooltips are great for clarifying where links lead. Use <title> instead of <alt> for your tooltips (read Roger Johansson’s Alt text is an alternative, not a tooltip for an explanation of why).

If you have to use technical language, such as abbrevations or acronyms – make sure to use <acronym> for acronyms and <abbr> for initialism and when in doubt (read Lars Holst’s excellent Abbrevations, Acronyms, Initialisms for a detailed discussion of why). This provides the users with easy access to explanations for the tricky terms without having to leave your site.

Think of your user as intelligent, in a hurry and an expert in their own field, which is usually not the topic of the instruction. Don’t be insulting or patronizing – nobody likes that.

Make your instructions easy to navigate. Make them searchable.

Be witty if you can. But don’t be witty in the wrong places. If the user is already frustrated about the problems she is experiencing (probably because of something you did wrong), don’t make bad jokes on her expense.

And when you think you are done:

Put your instructions to the test with real users (or the closest thing you can get to real users). Only then will you know if they actually work.