Leah Guren gave an excellent overview of what Technical Communicators should take into consideration to make their documents better and packaged it in ten tasty tips.Leah Guren gave an excellent seminar talking about one of the many things she does best–teach how to make Technical Writers Write even better. Intel at Matam was the host for this STC sponsored event, but the room was packed with many non-STC members, as well as members of Elephant.

For anyone who has taken Leah’s course, and many in the audience had, it was a great review of most of her golden rules. Leah made it clear at the start that this was not going to make all of us great writers, but any of us who would take at least one tip to heart, would be better writers.

Historically, Technical writing used to be not much more than a description about a product, to bring the user closer to the product. It has now evolved to bring the product, and the documentation how to use it, closer to the user. How do we do this? It is all in the procedure. The procedure is more than just how to do something. A good procedure gives the right information, at right time, and also, in the right sequence. With this evolution in Technical communication, if someone would ask for a procedure and then get a description, it is not acceptable. “This,” Leah put it bluntly, “shows the difference between a real Technical Communicator and a hack.”

So why do procedures fail? Leah describes it as the jigsaw puzzle theory:

1-No picture on the cover corresponds to no label for the procedure

2-Missing pieces of the puzzle equals missed steps

3-All the pieces are there, but there’s an extra piece. Extraneous information is also confusing for the user.

So here are the tips and a sentence or two about each one:

#1–Analyze the audience:

Identify your users. What is their background? If necessary, create a persona for the user(s) to help you focus. You may need to write on more than one level for different users.

#2–Target tasks:

Get away from features. Consider the work flow of you persona. Brainstorm with others to get the feel of what you need to document. Name the procedures in the users’ words by using meaningful verbs.

#3–Signify through structure:

Avoid blocks of text, but be consistent with visual cues. Be clear with relationships and hierarchies.

#4–Walk through the why.

Limit the intro to two sentences explaining when or why a user would do this procedure. Don’t assume everyone knows why. Differentiate between similarly-named procedures. Use cross references when necessary. Arrange the tasks in the manual to follow how you think your persona would do it.

#5–Present prerequisites

List what’s needed before the user starts. Consider everything, including the time it takes to do the procedure. Do you need work space, protective clothing, administrative privileges, or even access to electricity? Don’t list the obvious.

#6–Smooth out steps

Use clear present tense imperatives: do this, do that. Talk directly to the person and keep it short. Chunk based on complexity.

Limit the number of steps. Keep the user from getting lost by using shorter procedures that can then tie together. Use signposting for longer procedures.

#7–Layer levels

Support mixed audiences for a procedure. Use consistent cues for landmarks, orientation, and confirmation. Use chunking and advanced information for the advanced users. Don’t forget to use verbal signposting.

#8–Highlight hazards

Almost every document has warnings, but look for the hidden hazards. Distinguish global hazards from step-specific ones and place them where needed. Use the appropriate signal word and icon. Keep it in clear “Do/Do not” wording. The average user may have no idea of the difference between Caution and Warning. If there are legal ramifications or specific safety guides, such as OSHA guidelines, hazards must be more specific. Make sure your icons are recognizable as hazard icons and don’t use too many on one page. Your user will make mistakes, but worry about where they will be critical, such as system crashes, lost data, etc. Remember to state the ramifications or importance of ignoring the hazard.

#9–Get graphic

Communicate visually, but don’t put in a graphic that doesn’t belong; the wrong image can distract the user. Button icons are essential. Introduce the graphic before using it. Don’t be lazy and use graphics instead of words and don’t use digital photos when a simple line drawing can be clear and give more information. Don’t use the graphic without introducing it.

#10–Test test test...

Find appropriate testers. Make sure you are testing the document and not the user. Have people “think out loud” during testing to help you find what you missed. Observe without interfering.

My apologies, especially to Leah, for taking so long to get this written and posted.