Sanjay Shukla

Writing Helpful Help – A Minimalism Checklist

| | Content Writing

User documentation is all too often written by programmers for programmers. It tends to focus on the product’s features, rather than the user’s tasks. Generally, programmers aren’t in the ideal position to be writing user documentation. They’re too close to the bits and bytes, and they’re too far from the user. To them, what the product can do tends to be far more important than what the user can do with the product.

 

User documentation is all too often written by programmers for programmers. It tends to focus on the product’s features, rather than the user’s tasks. Generally, programmers aren’t in the ideal position to be writing user documentation. They’re too close to the bits and bytes, and they’re too far from the user. To them, what the product can do tends to be far more important than what the user can do with the product.

It’s a subtle – but vital – distinction. Research shows that the key to effective user documentation is writing task oriented help. Even better, write your help according to the minimalist theory. In the documentation world, “minimalism” is a fancy word for a commonsense practice. In basic terms, it means write to your reader and keep it simple.

The theory itself has a lot of twists and turns. If you want to read a great – but slightly wordy – book on the subject, check out the book “Minimalism Beyond the Nurnberg Funnel”, 1998, edited by John Carroll.

In the meantime, if you can tick every item in the following checklist, you’ll be well on your way to usable online help that both your readers and your managers will thank you for.

Helpful Help Checklist

1. Base the help on real tasks (or realistic examples)

2. Structure the help based on task sequence – Chapter headings should be goals and topics should be tasks

3. Respect the reader’s activity – this is generally more about what you don’t do than what you do. Don’t waste the reader’s time by diving off into tangents

4. Exploit prior knowledge and experience – Draw the reader’s attention to previous tasks, experiences, successes, and failures

5. Prevent mistakes – “Ensure you do x before doing y”

6. Detect and identify mistakes – “If this fails, you may have entered the path incorrectly”

7. Fix mistakes – “Re-enter the path”

8. Provide error info at end of tasks where necessary (rule of thumb, one error info note per three tasks is a good average)

9. Don’t break up instructions with notes, cautions, warnings, and exceptional cases – Put these things at the end of the instruction, wherever possible

10. Be brief, don’t spell everything out, especially things that can be taken for granted

11. Omit conceptual and note information where possible, or link to it. Perhaps provide expansion information at the end of the topic, plus maybe a note that there are other ways to perform the task/goal, but this is the easiest

12. Sections should look short and read short

13. Provide closure for sections (e.g., back to original screen/goal)

14. Provide an immediate opportunity to act and encourage exploration and innovation (use active invitations to act, such as, “See for yourself…” or “Try this…” rather than passive invitations such as, “You can…”)

15. Get users started quickly

16. Allow for reading in any order – make each section modular, especially goals, but perhaps tasks (definitely if they can be performed in different order)

17. Highlight things that are not typical

18. Use active voice rather than passive voice

19. Try to account for the user’s environment in your writing

20. Before writing anything, ask yourself “Will this help my reader?”

By building these practices into your documentation process, you’ll find that your online help becomes easier to write, shorter, and far more usable for your reader. What’s more, your boss will love you!

Should You Write a Long-Copy Ad or Keep it Short?

| | Copy Writing

Should you write a long or short ad? The truth is, the reason people read ads has nothing to do with copy length.

 

Okay, you’re ready to write the ad of a lifetime. The one that will pull like crazy and leave them begging for your product like Somalians for food. So, do you whet their appetite with a short and sweet ad? Or write a long-copy ad that’s stuffed with information?

The 80-20 rule says 80% of the people only read the headline (and maybe a caption, if you have one). But the fact is, readers will read a long-copy ad. One McGraw-Hill study looked at 3,597 ads in 26 business magazines. What they discovered was that ads with 300 or more words were more effective that shorter ads in creating product awareness, inducing action and reinforcing the decision to buy. Another ad for Merrill Lynch crammed 6, 450 words into a single New York Times page. It pulled over 10,000 responses—even without a coupon! The truth is, the reason people read ads has nothing to do with copy length.

“Nobody reads long ads…” and other urban ad legends

People shun too many of today’s ads—long or short—because several misleading myths have stubbornly remained with us. Things like “negative headlines are a downer since people want to feel good when reading your ad.” Or “show the product or they’ll never know what you’re selling.” Then there’s the stuffy axiom, “there’s no place for humor in business advertising. “ Or the ubiquitous saw, “all your ads should look the same, blend in or be swallowed up.” The list goes on and on. Presented with unabashed hubris by the high priests of advertising. The basic fact is, ads really fail for three reasons.

Your ads are all about you

You’re telling customers what you want to hear, not what they want to know. Impressive sounding features are fine to motivate your sales force, but your customer is only interested in one thing: “What’s in it for me?” This offense is particularly egregious in business-to-business advertising, which is infamous for its addiction to phrases like “the XP90 does it all” or “now with Duo-Pentium Processor”—without a hint of what these features do. Also contaminating many of today’s ads are such chest-pounding headlines as “Taking the lead,” “The promise of tomorrow, today,” or “A tradition of quality.” They sound good but say nothing.

Your ads are boring

You’ve got to break the boredom barrier—big time. Many ad gurus say blend in, be one of the pack and survive. No wonder so many ads look alike, proudly showing big pictures of their products, or worse yet, featuring a giant photo of the company’s CEO—usually with a caption that’s been scrubbed clean of originality or compelling information. If you want people to stop and read your ad, you have to make the ad more interesting than the editorials in the publication you’re in. Give them real news, a fresh new way to look at what you’re offering them. Stand out from the crowd. Start trends, don’t follow them. One of the most interesting car ads I ever saw showed the car only sparingly; instead, it featured an animation of a human heart beating furiously to the soundtrack of an accelerating engine. Breakthrough stuff.

Your ads don’t make human contact

They’re not reaching readers on an emotional level. We all want to be liked, appreciated and loved. We want to feel secure in our lives and our jobs. So be a mensch. Create ads that touch the soul. Use an emotional appeal in your visual, headline and copy. Don’t just show a car on the road; show the guy captivating his sweetheart with the car. If your buyers were on the moon, would they care about your car’s styling? No. They’d get an ugly, crawly vehicle that got them from crater to crater. Selling computers to business? Show the guy getting a raise or promotion for selecting your latest model. You’re selling the emotional end result, the human need-based bottom line, not a box, or vehicle with four wheels and an engine.

So if you’re struggling with the notion of whether to write a long- or short-copy ad, you can do both and still get results. The key is not length or lack of it, but information, interest and involvement in your customer’s needs. These are the ingredients to creating a successful ad.