How to Write Excellent Online Instructions
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.
5 Comments
Insulted female - October 11, 2011 at 20:30
Hello – I did a Google search and came across this article. While I understand that you are trying to be helpful, I don’t appreciate the intermittent use of “she” and “her” in your article. You made somewhat of an effort to keep things gender-neutral by using words like “user” and “their” when referring to your subjects. However you slipped up and showed that you clearly had ignorant women in mind when you were writing this. I’d like to recall your line about, “Don’t be insulting or patronizing – nobody likes that.” Well, you’re right – nobody likes that. Please make a greater effort to keep your private thoughts about the intelligence of women, well, private. Thank you.
Mattias - October 13, 2011 at 08:34
Hi and welcome to the blog!
As you can see, this piece was written almost four years ago so I had to go back and reread it again in light of your comment.
I sincerily apologize if you felt offended with my sporadic use of she/her. It was simply my attempt at breaking the norm of using the male pronoun as a default, but I can now see how it came across as insulting instead, the opposite of my intentions.
I don’t see users as ignorant, hence my tip: “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.” I’m a bit confused as to how you take that to be about me thinking about “ignorant women”, but clearly I need to communicate my point better.
Again, my apologies for having offended you and I do appreciate the comment. I’m also curious what search terms you used when you ended up at this blog post, it would be really interesting for me to know.
Best regards,
Mattias
new puppy training - February 10, 2012 at 03:49
puppy training advice…
[...]we found this article to be an excellent source of information and highly recommend it as a source for the project[...]…
Elisha Kohl - April 30, 2012 at 23:59
Hello there, whenever I go to this particular site I almost repeatedly get this error message 401 Internal Server Error; Just assumed you would like to know.
Jeff - August 10, 2012 at 13:17
You know, this discussion just popped in to my head today for some reason, I think I saw an article saying he/she… I remember when the comment by insulted female was posted, and how upset Mattias was at the time… Anyway, somehow I started thinking about this today, I thought I would like to comment…
I think there may be a large amount of cultural bias in this discussion about Mattias’ intentions.
I am from North America, and I am well aware that women tend to be marginalized in that culture, at least where I am from. So, I can see being a women from that culture would make you alert to this type of behaviour…
However, Mattias is from Sweden, where I have had the pleasure of living the last 6 years of my life. I can tell you that women are by no means marginalized in that culture. I think that it is a society with more equality then any I have seen before.
What I am driving at is, perhaps Mattias’ slight was merely because in his mind there was no need to think about the issue at all, because culturally and personally, he has no hang ups in this area. It is therefore not something that ever enters his thought process…
That’s just my thinking, and probably no one actually reads this because it’s so late after the post… But there is my 2 cents anyways.
Leave a Comment