Because I am both a technical writer and a software tester, one of my pet peeves is an interface that falls apart when it needs to communicate anything to the user. On every project I see code instead of text, poor grammar and spelling, ALL CAPS, odd choices of punctuation marks and a great many other sins against language. But the most basic mistake is simply not to understand that it’s okay to talk to the users in clear, simple language.
One of the challenges of project work is that you have to get into things quickly and without much help – in many places, people will have neither the time nor the inclination to teach you.
Remember that if you want to write about how something works, you have to understand the why of it as well. Users have to be given a context in which to work, a logical explanation to why things have to be done a certain way. It makes it easier for them to remember, and it removes the frustration users experience when they think an application is making them work hard for no real reason. So it’s not enough just to figure out the UI to stay one step ahead of the user – you have to really understand what’s happening.
The natural assumption of most software companies is that an application intended for experts in the field doesn’t need to explain anything beyond the interface. The user is supposed to know the work-flow and terms at least as well as the manual’s writer.
But the reality is that many people are trained in the field and the software at the same time. This is true not only for the application’s users, but also for its future programmers and testers. There are also users who are experts in the field but not be familiar with all its possibilities – especially ones that are unique to your application. And some might have all the required knowledge, but in a different language.
Scanning is the quickest way to get through reading material: glance at it just long enough to find the bit you’re interested in. It’s a big time-saver for readers and they’ll thank you for making your text as easy to scan as possible.
The readers’ scanning speed is determined by your writing and formatting decisions. For the purpose of this article, I’m assuming your text is a user manual, training guide or any other text intended to explain an application. There are several things you can do with such texts to make them easier to scan. I’ll start with writing tips, and move on to formatting.