writing When the subjects of usability and user friendliness in relation to documentation are broached, writing isn’t often the first thing that comes to mind. But it should be.

Not matter what you’re writing — a manual, online help, a quick reference, or a script for a screencast — the writing is what’s going to make or break your work. Not the tool you’re using. Not the methodology you’re using. Not the formatting of the document. The words.

Making documentation more usable and user friendly can also involve changing the style of writing that you use.

Words to write by

Tim O’Reilly (yes, that Tim O’Reilly) had this to say:

People are looking for advanced tips and tricks. They’re not looking for the basics. They’re looking for things that will give them more of an edge. And they’re looking for it in a style that’s fun and engaging.

Admittedly, O’Reilly was talking about the books his company publishes. But the last sentence in that quote is the key: they’re looking for it in a style that’s fun and engaging.

Too often, the style of writing used in documentation is stiff, a tad formal, and can be verbose. Don’t get us wrong here. We’re not stating or implying that you can’t write. Sometimes, though, technical communicators get a bit complacent or just plain caught up in a set of writing standards. We have in the past. And those factors can get in the way of what’s crucial when developing information for users.

Going a little more casual

We’ve probably all been taught that we need to write in a more formal tone. Admittedly, there’s not a whole lot wrong with that. Technical writing doesn’t have to be scintillating prose a la … well, fill in the name of your favourite novelist here (I’m partial to James Salter myself). But documentation doesn’t have to be dry and boring like an academic tract or the articles that are published in a certain periodicals.

A key to writing documentation that’s easy-to-read and packed with information is to write tightly. Keep it short and to the point. You’ll have to choose your words very carefully to get the information that you need to get across in the shortest form. Keep it active. Keep it interesting.

Write as you’d speak

You’ve probably heard people talking about documentation as a conversation. Why not interpret that literally and write as you’d speak? Clarity can come from writing in a more natural, conversational way. You might have to break a few rules of grammar. That shouldn’t matter if your writing is clear and gets the point across succinctly. Tom Johnson shared a few interesting thoughts on this recently.

Of course, you want to eliminate all of the the umms, ahhs, and y’knows. Eliminate the pop culture references, clever turns of phrase, and jokey allusions that you might normally use when speaking to friends, family, or colleagues.

Assume that you’re writing for the Web, even if you’re not. One piece of advice that’s given to aspiring Web writers is to limit sentences to 20 words. Preferably less. You don’t need to view that as a hard and fast rule, though. If you need to write longer sentences to achieve clarity, by all means do so. Here’s an example:

Something I see a lot of in documentation is phrases like … based on application status … Who speaks like that? Instead, why not write something like … based on the status of the application … The latter sounds natural.

Thoughts? Feel free to leave a comment.

  • Share/Bookmark
Print

Related posts:

  1. Write documentation as if writing for the Web
  2. Writing an interface style guide
  3. A few thoughts on documentation for the power user

Related Posts