Designing Effective Online Help

Speaking plainly

If you're an English major, you'll have to fight the urge to produce documentation that is full of, well ... big words and complex sentences. Online help is supposed to help people learn. People shouldn't have to use a dictionary to understand what you're writing. The best thing to do is use smaller words that are in common use. This makes your online help easier to understand and puts your users at ease.

You can do a few simple things that will make your writing more understandable.

You should avoid using adjectives and adverbs. For example, "Use the widget to produce graphics," and not "Use the widget to effortlessly produce graphics." Effortlessly conveys no valuable information and it's completely subjective. Maybe someone will find using the widget to be absolutely impossible!

You should also avoid marketing lingo. Marketing uses words to sound impressive while conveying no real information. "The widget dynamically promotes effective graphical solutions," is just grotesque and pointless. It conveys no real information and it will leave users wondering about the meaning of the sentence.

Finally, avoid buzzwords: solution, elucidate, empowers, and proactive are just a few of the ones that really irritate me. Buzzwords come and go. You want to stick with vocabulary that won't make your documentation look like a pop culture magazine (unless that's what you're writing for).

I think I can demonstrate what I mean when I say "speak plainly" by relating an anecdote. I recently went into a rest room stall in an office building. I noticed a green note taped to the back of the stall door. A white note was taped over the green note. Being curious, I lifted off the white note to see what was written on the green note. The green note read something like this "Due to very minimal pressure in this facility, excessive use of paper materials necessitates frequent attention." The white note read "Flush often to avoid backup."

Which note is easier to understand?

---