Wednesday, September 26, 2007

Campbell - Chapter 4: What’s the Best Way to Word This?

Writing Effective Policies and Procedures: A Step-By-Step Resource for Clear Communication

Nancy J. Campbell

Chapter 4 - What’s the Best Way to Word This?

Technical vs. Narrative Writing

Campbell begins the chapter by attempting to explain the technical writing style. The writing that most of us learned in school, she terms “narrative” writing, a style which makes use of “complex grammatical structures” and is often descriptive, lengthy, and complicated. Policies and procedures, she argues, should employ a form of technical writing that emphasizes clarity and speed of transmission.

The Old Rules

In this section, Campbell reiterates her belief that our educational system equates verbosity with quality. Policy and procedure authors, she concludes, must shed this inappropriate mindset.

The New Rules

Effective policy and procedure writers, Campbell asserts, adhere to the maxim, “Simple is good.” She decries padding, complex sentence structures, and fancy vocabulary.

Being A Word Miser

In the pursuit of verbal simplicity, Campbell suggests that text should be limited to only those words absolutely necessary to convey the intended message. She offers several tips to help in achieving this goal:

Think in Ones

Eliminate unnecessary adjectives, prepositional phrases, and extra clauses, using only those words necessary to convey your main point.

Dump Pompous, Stuffy Language

Eliminate “windy, stiff language” by following Campbell’s word miser rules, to be discussed later.

Speak to the Reader

Try to write as though you were speaking to your reader in person. Avoid the “flabby, excessive writing”, that comes from dressing up common words (e.g. useutilize, start→initiate, etc.).

Follow the Word Miser’s Rules to Live By

The use of active voice clarifies roles, and writing in the present tense gives a desirable sense of immediacy. This is true, suggests Campbell, even when these techniques lead to the use of improper grammar.

Be an Accurate Word Miser

Here, Campbell reminds her readers that brevity should never come at the cost of clarity. When cutting words, do so judiciously to avoid introducing uncertainty and confusion.

The Word Miser’s Rules to Live By

Here, Campbell summarizes her suggestions in a list of 17 rules for effectively communicating policies and procedures. Many of these are accompanied by examples.

1. Use common words and phrases.

2. Use one- and two-syllable words.

3. Get rid of windy phrases.

4. Get rid of redundancies.

5. Get rid of empty phrases.

6. Eliminate all unnecessary adjectives and descriptions.

7. Limit the number of clauses and phrases, and keep them short.

8. Use short sentences.

9. Use short paragraphs.

10. Use one-sentence paragraphs.

11. Keep phrases and clauses short.

12. User transitions at the start or sentences and paragraphs to tell readers what’s happening next.

13. Use lots of lists.

14. Use active voice.

15. Use present tense.

16. Start with an action verb.

17. Use standard word order of subject-verb-object.

Being a Word Master


In this section, Campbell offers additional tips for becoming a “word master”, or “one who uses words with precision and respect”. These include:

Say What You Mean and Mean What You Say

It is important to be mindful of the vast range of possible misunderstandings inherent in even the simplest of phrases. This requires precision in communication, which may trump the goal of brevity.

Use Specific Language

Policy and procedure writers should avoid words that invite varying interpretations. These include “weasel words” such as “may, might, could, should, etc.” Each of these words has a precise meaning that must be fully understood.

Developing a Rhythm

Here, Campbell introduces the concepts of consistency and parallelism, which contribute powerfully to reader interest and comprehension.

Consistency

Varying words and terminology can confuse readers, so use terms consistently throughout a document. This is one area in which creative wordplay can degrade clarity.

Parallelism

Parallelism simply refers to the technique of using the same grammatical format for like items. Varying grammatical constructs makes instructions awkward to follow.

Being Correct

It’s extremely important to avoid mistakes in grammar or usage, states Campbell. Such errors can lead to confusion, misinterpretation, and mistakes. To help avoid these issues, policy and procedure writers should refer to style guides as needed.

Considering the Reader

This section offers information on writing in such a way that is relevant to one’s readers. It assumes that one has performed the audience analysis.

Don’t Assume Anything

Do not overestimate the knowledge or experience of your audience.

Look at the Reader’s Experience

Reexamine your audience analysis, and in most cases, target your writing to your most inexperienced readers.

Use Jargon Carefully

Some considerations regarding jargon include:

  • Even experienced users may not be familiar with it.
  • It can be cumbersome and difficult to understand.
  • It can be faddish and pompous.


Distinguishing Between Users and Readers

When writing policies and procedures, give precedence to the needs of your users over those of your readers.

Calculate Reading Level

Make use of software-based or manual reading level calculations to ensure that you are writing at an appropriate level for your audience. This is frequently in the range of a 6th-8th year reading level.

Word Documents Carefully

Using words that provoke unpleasant reactions will reduce our audience’s receptivity to your message.

Using Special Techniques for Procedures

Special technical writing techniques exist that can help maintain a high level of clarity when writing, thereby reducing the serious risks associated with unclear policies and procedures.

Start With an Action Verb

Policy and procedure users are generally looking for an answer to the question, “What do I do?”. Beginning one’s sentences with action statements offers them a clear reply.

Use One Action per Sep

Steps that contain more than one action “confuse the reader and bury the message”. Most procedures should be broken down into their most basic, individual steps. Exceptions to this may be made in cases where the nature of the procedure is such that combining steps increases the clarity of instruction.

Assign the Action

When there are multiple actors involved in a procedure, it is important to clearly state who is responsible for each step of the process. Avoid using indefinite pronouns.

Pack a Sentence

Readers tend to remember the first and last parts of a sentence best, so in some cases it is useful to arrange your words to capitalize on this phenomenon.

Choose the Right Format

Adhering to strict format guidelines can help a policy and procedure author adhere to all of these suggestions automatically.

Tools and Resources

Campbell concludes her chapter with a collection of lists, tip sheets, guidelines, and formulas to aid in the construction of policies and procedures.

Barker Chapter 4

Writing to Support – Reference


Barker discusses the third level of the levels of support, reference documentation, also known as support documentation. Barker defines and explains the purpose for the three types of reference information:

Appendices: which allow the documenters a place to put all the highly detailed, technical information that the technical users would want to use in the workplace. The appendix is relevant and useful but may not be essential to all users. Some examples of items in the appendix are:

  • Error messages and explanations of how to recover from them.
  • Filenames and extensions of files associated with the program.
  • Troubleshooting tips.
  • Matrixes of compatibility with other programs.
  • Charts showing program key combinations.
  • Printer driver charts showing capabilities with various printer brands.
  • FAQ.

Update Information Sections/Readme Files: Consist of text files that accompany programs either with an additional disk or download from an internet site. They serve the purpose of informing the user of new information, installation details, last minute changes, new features, etc.


Job Aids: also known as job performance aids, are shorter forms of reference documentation that include keystrokes, definitions, brief processes, command summaries and other information useful to users. The purpose of the job aid is to provide useful information at the point of need. They consist of a number of forms such as; keyboard templates, cheat sheets, laminated program cards, quick reference cards, and other forms. Another variation of the job aid is the innovative forms: Flipcards, the purpose of the flip card is make it easier for the user to simply flip through the information he or she is searching for.

Innovative Forms: Flipcards This section Barker also discusses as an easy to follow format it is technically classified with the job aids. The flip card is valuable because:

  • Easy to read
  • Contains a surprisingly large amount of information
  • Colored headings
  • Unique and interesting
  • Affords easy access to information.

Barker also discusses the importance of what to include in your reference guide, he breaks up the reference specifications into three main groups:

  • Commands: refers to all the instructions the user uses to make the program work.
  • Information about the commands would include:
  • Meanings of special function groups
  • Explanation of set commands
  • Definitions and use of format commands
  • Special procedures for using utilities
  • Explanations of toolbars
  • Definitions of macros

Interface Elements: Refer to the parts of the screen that the user sees and has to manipulate in order to use, these include:

  • Explanations of menus
  • Definitions of keys
  • Labels of screen regions
  • Explanations of rulers

Definitions of Terms (Glossary)

  • Concepts that underlie the software
  • Terms relating to the subject matter of the software

Barker also discusses the importance of organization either alphabetical or menu-by-menu. Menu-by-menu may have more advantage because the user is used to seeing that format. He also states that you should explain to the user how and when the reference guide should be used. It is different from teaching or guidance level of support, it is there to inform the reader not to give a “how to”.