Some Best Practices When Writing Help Documentation


*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

If you are planning to create online help documentation and want to make sure you end up with one that is truly helpful, here are three best practices you can follow to make sure it is:

  • Tailor it to users who have with varying skill sets and goals.
  • Review, test, and update it for accuracy.
  • Create context-sensitive topics.

Keep different users in mind

You can’t always predict what every user will know or want to know about any product. On one hand, if you oversimplify help steps, users might get confused. If you provide too much detail, they might get frustrated or bored.

One way to alleviate this problem is to divide help topics into several different types that target users at different skill levels by varying the kind and amount of information you provide. For example, you might have an overview topic, such as a definition of a specific system function, and then provide a link to all of the tasks related to that function within the overview. That way, users get just the specific steps they want.

The key is to allow users to navigate the help documentation to find (or avoid) as much detail as they want.

Continue reading

Tips for Writing With a Personal Stye

Written by Leslie Brown

I read something the other day that went like this: “Being human is the new black.” I think it’s true. Today, writing with a more personal style is almost expected.

This style is characteristic of the human-like voice of Siri, the digital personal assistant that comes with the iPhone. In an almost friendly way, she tries to understand questions and then proposes what you hope will be a helpful answer. Before responding, the voice says something reassuring like “Let me check on that” or “Let me think about that.” If the data isn’t available, she simply says, “I can’t answer that.”

Continue reading

Design for How People Learn

book_coverWritten by Julie Hale

My training in technical writing has made me want to learn more about the field of instructional design, so I recently read an interesting book called Design for How People Learn by Julie Dirksen (New Riders Press, 2012). The author makes good use of photographs, cartoon-like drawings, mock screenshots, and other graphics. The book’s tone is conversational, and the author uses current cultural references and her own experiences to provide context for the ideas she presents.

Dirksen does a great job of laying out the basics, which makes the book particularly valuable to anyone without an extensive background in instructional design. She discusses skill vs. knowledge, explains why some teaching methods don’t work well in time-compressed situations, and describes the difference between a motivation gap and a knowledge gap. Her observations are thoughtful and her analyses extend beyond the teaching method. Sometimes, she notes, an instructor may not be dealing with a learning problem—instead, the problem may involve another factor like leadership or style of communication. The author also believes that while learners can’t be forced into being motivated, it is possible for good instructional design to help promote and support motivation.

Dirksen’s clear and logical explanation of key concepts and her focused writing style makes the book a quick and engaging read. I recommend Design for How People Learn to anyone interested in knowing more about how to convey information effectively.

Have something to add to this story? Share it in the comments.