Writing help for those who actually need it

June, 2011

Help by Dimitri N.

help by Dimitri N.

“Turn ‘GAS COCK KNOB’ to PILOT index on gas flow regulator.” I’m sorry, what? This is actually one of the more decipherable lines within the owner manual for my water heater.

Earlier this week I had the misfortune of coming home to a flooding garage. It turns out my water heater was leaking. As part of the repair I turned off the gas and water for safety. I was at the point of turning it all back on and was befuddled by the help I was provided. It clearly wasn’t written for a layman.

Who needs your help?

The problem is that the people who understand jargon and complex contexts don’t need instructions. They can do this stuff in their sleep. Laymen like me need instructions. And the same is true for your application.

The people who need help on your site are lost, confused, and in need of soothing, practical, and readable advice.

Who writes your help?

There’s nothing wrong with industry jargon when used amongst others who speak it’s tongue – it’s a more succinct conversion for them. Jargon, when defined and used consistently can actually help an industry or vertical to mature as the collective group of people stand on common ground.

The problem is that it’s far too common to find help that was written within this jargon. While I’ll admit that this is the right place to introduce it, it’s not the right place to assume it’s already understood.

Simplifying help

Make help accessible to people who are new to your field or who may have been practicing in isolation. Don’t be afraid to use terms that are more common, or to provide asides that explain new concepts when they are introduced. It’s also a good idea to use alternative, friendly descriptions of objects to ensure that you are on the same page.

Here’s a good rule of thumb:

If a help topic read out loud to someone once is not understandable, and executable, then it is too complex.

I rewrote that line 4 times to reduce complexity and increase clarity. Because this whole blog post is a help topic, and you have to ensure readability of all help topics.

What next?

Here’s something we did in an industry group I worked on within the email community a little while back. We asked non-industry people, like your parents or friends outside of work, to review help and informational documents that we had created.

That made sure that it was something anyone could grasp, and we weren’t writing for experts who didn’t need help.

So keep in mind your target market and write some help that is actually helpful!

  • http://ericboggs.com Eric

    I see what you’re doing here, Adam…and I’ma let you finish. But – you will not win the battle of the blogging Argyle founders! :)

  • http://adamcovati.com Adam Covati

    Bloggerdome. Two founders enter, one founder leaves.

    It has begun.