Barker Chapter 4 – Writing to Support-Reference

by Mary Dobbins

Chapter 4 deals with the three main levels of support: teaching, guidance, and reference. The level of support used is determined by user behaviors, questions, and needs. The various forms of reference are described as follows:

- Appendices – highly detailed, technical documentation such as error messages explanations, filenames and extensions of files associated with the program, troubleshooting tips, compatibility information, fast-key options, printer driver charts, and FAQ

- Readme files – installation details, changes not included in the manual or online help, new features in program, revision histories, errors in manuals and online help, file descriptions, contents of directories, installation tips, and compatibility requirements


- Job aids – shorter document that may include keystrokes, definitions, brief processes, command summaries and other useful information

- Flipcards – contains brief program information on a card that fits on a monitor. Typically, flipcards are easy to read, contain a lot of valuable information, use colored headings, are unique and interesting, and offer easy access to information


When developing references, you must decide what to include. The text suggests:

- Commands – explanations of set and format commands, special procedures, and toolbars

- Interface elements – explanations of menus, keys, screen labels, and rulers


- Definitions of terms – glossary

References should be written in a consistent pattern and arranged in a manner that makes sense to the user such as alphabetically or preferably, menu by menu. The text indicates it is necessary to show the user how to use the references and also to understand how the typical user will use the references.

Chapter 4 (Campbell) Group 7 Jaeger/Lopez

What’s the Best Way to Word This?

Technical vs. Narrative Writing

Technical Writing – purpose is to get the message across quickly and clearly
Narrative Writing – purpose is to impress the reader

*Clarity and Speed are the only two criteria’s needed to write technically. If users clearly understand what’s expected of them and can understand it fast, you have a successful document. Simple is good. Get rid of pompous, stuffy language. Eliminate unnecessary verbiage.

The Policy and Procedure Writers Oath – I do solemnly swear to avoid excess verbiage, fancy phrasing, and long words and sentences. I will resist the temptation to display my grammatical mastery and linguistic skill. I will devote myself to the pursuit of short, clear messages. I will dazzle with speed and clarity. ( Ha ha, I love it!)

Being a Word Miser

People who use only the number of words necessary and want to get rid of every single word that doesn’t mean something. To become a word miser follow these simple steps:

Think in Ones

One word is better than two. Two sentences are better than three. They look for any additional words that they can take out but still have the same meaning. Example:

Use the designated hammer.

Do you really need to specify designated?

Dump Pompous, Stuffy Language

Use active voice, start with an action verb, and eliminate all unnecessary adjectives. Example:

All rental car reservations must be made through our affiliated travel agency.

Better -> Reserve rental cars through our travel agency.

Speak to the reader

Type like you are directly talking to the reader. Simple, common language is exactly what you’re looking for in most policies and procedures. Talk to the readers out loud, then write down what you would say.

Follow the Word Misers Rules to Live By Think active voice, present tense. Subject, verb, object. Form your sentences this way, it is called active voice. Active voice cuts out a number of words and clarifies who does what. Add present tense to give a sense of immediacy.

Be an Accurate Word Miser

Be sure not to take out critical information. Don’t cut words mindlessly. Always ask whether a word or phrase adds any meaning. And if you can’t be both brief and clear, always choose clarity.

Being a Word Master

Use words with precision and respect. Instead of using very long sentences to describe procedures, break instructions into steps; numbering or lettering them.

Understand that every word has a meaning. Describe statements like: Turn the handle to the left. More like: Turn the handle slowly to the left until it stops. Do not force the handle. Say precisely what you mean.

Say What You Mean and What You Say

Use Specific Language

Avoid vague words that invite varying interpretations. Describe what “cool” is not by a word, but rather “45 degrees Fahrenheit”.

Developing a Rhythm

Rhythm is what keeps the reader reading. Two sources of rhythm: consistency and parallelism

Consistency

Varying your words often confuses the readers. Use the same word to describe the same action or object throughout. Creativity doesn’t count.

Parallelism

Use the same grammatical format for like items. Use the same future tense or the same passive or active voice to make instructions parallel in form.

Consider the Reader

Don’t Assume Anything

Don’t assume the reader will understand. Statements that require prior knowledge assumes the readers know what to do. Do not fall in this trap.

Look at the Reader’s Experience

Pay attention to your audience. Diversity of user experience poses a challenge. Visualize the least experienced user and write for that person.

Use Jargon Carefully

Don’t presume that terminologies are common just because you know them. Once again, analyze the audience carefully.

Distinguish Between Users and Readers

Users take action, readers don’t. Write for the user.

Calculate Reading Level

Well over 50% of today’s workforce reads below a ninth-year level. You must consider this. Write for the 6^th – 8^th grade reading levels, the same as most newspapers write to.

Word Documents Carefully

Using Special Techniques for ProceduresAvoid words that provoke unpleasant reactions. It will increase receptivity and reduce resistance.

(These are pretty simple so I am not going to describe them too heavily.)

Start With an Action Verb

Use One Action per Step – makes instructions easier and faster.

Assign the Action – If multiple users are involved, it’s critical to clarify the responsibility.

Park a Sentence – The most powerful position in any sentence is the beginning and end. Place keys words first and last.

Choose the Right Format – Play script is the best and clearest format for most procedures involving more than one person. Outlining and lists work well also.