How to write longer Help

Inspired by a tongue-in-cheek U.S. Government article about how to write longer sentences, I offer the following ironically brief tips about how to create Help pages that are sure to overwhelm users with their complexity and excess verbiage:

    Assume your reader is an idiot. Spell out every acronym, no matter how meaningless the expansion will be, and define every term, no matter how common or basic.

    Eschew combining steps into logical and natural groupings. Break all procedures down to their smallest element so that all of your numbered steps are as long as possible.

    Include as many pictures as possible. Be sure that almost all numbered steps include screenshots of the UI elements that users have to interact with, even buttons and menus. (See "Assume your reader is an idiot," above.)

    Write passively. You should narrate the action for the user, speaking in an authoritatively detached manner. For example, instead of writing "Click OK to save your settings," use "After clicking the OK button in the lower-right corner of the dialog, the selections you made will be saved for future use."

    Cross-reference extensively. If there is another Help topic that is related in any possible way, you should link to it. You want to make sure the reader knows that there is a world of information available to them, and encourage them to explore it at the expense of accomplishing their current task. Preferably, use embedded hyperlinks to ensure that every page is a sea of blue underlined links, which is very pretty.

Don't be discouraged if these tips sound like a lot of work. By examining help systems for many products you'll find that your fellow writers utilize these techniques quite extensively. So surely, they're key to tech writing success.

Thanks to Mike Pope for the plain-language link.

Posted: November 5, 2006 link to this item, Tweet this item, respond to this item