Talking Shop: Keep users in mind when creating documentation

Tips for making documentation more user friendly

If you've ever wondered why consulting the manual is the last resort for 99 percent of users who need help, then wonder no more. It’s because the same people that write the software or create the hardware often write the manual—often without the user in mind. When writing manuals, guides, or procedures, the most important thing to get right (after accuracy) is readability. Writing with the user in mind will help you produce a text that will actually be read instead of simply gathering dust on the shelf.

It's all about the user
Here are six tips to keep in mind so that your documents won't be ignored.

Keep the reading level appropriate
Avoid writing above or below your audience's reading level. For example, if I wished to explain to a TechRepublic member how to install a modem under Windows, I would start by writing, "Open the Modems applet in Control Panel." For a nontechnical person, I would explain things more carefully, perhaps, "Locate the My Computer icon on your desktop, double-click on it, double-click on Control Panel…" and so on.

Check for readability
A document that reads well is more easily understood. While mathematical readability formulas exist, I don’t bother with complicated stuff like that. They all sound too difficult to me. Instead, I read my work aloud. If I trip over clumsy phrasing and gasp for air between run-on sentences, I go back to the word processor. The other great advantage of reading aloud to yourself is that colleagues will assume the stress has been too much for you and moderate their demands on your time.

Hire a good translator, if needed
If your work will be translated into a foreign language, hire an experienced professional. Languages often contain idiomatic phrases that are well used in one language but, when translated into another, are meaningless or downright confusing. Think about commonly used expressions in your language.

The often-used English expression, "To pop out for a quick one," implies you are going to the nearest pub for a drink and will quickly return. Someone unfamiliar with this phrase might reach for an English dictionary and find that "pop" means to burst or explode. This would definitely convey the wrong message. This is perhaps a slightly irrelevant example, but it serves to highlight the need for clarity.

Use a fresh perspective
Get someone who doesn’t know the product to write the manual. This may sound a bit daft at first, but think about it. Give me a product that I know nothing about and tell me to write the manual. The questions I will ask will be the same as those of a new user. While there should always be constant communication between the writers and product developers, a fresh perspective is helpful for creating documents that new users will understand.

The best instruction manual I've ever written (in my opinion) was a beginner’s guide to Microsoft Access. Having never used the product, I stumbled in the same places as other beginners would likely stumble. The finished product was one written very much with the new user in mind, and it was more successful than any of my other works.

Limit the use of technical terms
Avoid as much technical jargon as possible without altering the document's meaning. If a simple term for an object or action exists, then use it. Once you have gained the reader’s trust and confidence, you can then proceed to use advanced terms, remembering to always explain new terms when they are introduced. Pictures, when used appropriately, are also a great way to convey meaning. A simple screen shot can be worth a thousand words, but don’t overdo the graphics.

Test your work on a guinea pig
My wife hates computers and has no use for them. She has never had a job that requires their use, and her IT skills are nonexistent. The acid test for any instruction manual or tutorial I create is, "Can Kate can do it?"

I give her the document, sit her in front of the computer, and get her to follow the instructions. If she succeeds in completing the task without asking any questions, I award myself a pat on the back. Any questions she asks I add to the text and try again. Repetition is the name of the game.

Are you a good writer?
Become a contributor to TechRepublic's Support Republic and shape your community. We're looking for support professionals who like to write, as well as writers who are familiar with the technical support industry. Article ideas will be reviewed on a case-by-case basis. If you are interested in writing for us, send us an e-mail with your qualifications, areas of expertise, and article ideas.


Editor's Picks

Free Newsletters, In your Inbox