Tech Comm Student

When ready to begin writing either a policy or procedure, one of the first steps is to determine the type of document format that will be most effective in communicating the information. Technical writers need to consider who they are writing for, who will need to know the information for implementation purposes, and how they prefer to have the information presented.

Primary Formats

There are four primary format types: narrative, outline, playscript, and flowchart.

Primary formats are those that are most commonly used in policy and procedures.

• A narrative format consists of a basic block of writing which runs left to right, and is usually contained within a single column on the page. Narratives are used for more policies than procedures.

• The outline format is similar to the narrative, but contains shorter sections of text that are clearly labeled. Outlines are generally easier to read for most users. Outlines can be used for both policies and procedures, but are more often found used in policies.

• Playscripts list the name of the person responsible for taking action (actors) next to the action(s) which must be taken. Many users appreciate how simple it is to quickly interpret a playscript. Playscripts are not appropriate for policies.

• The flowchart format uses symbols and arrowed lines to represent the flow of control. They are used in procedures more often than in policies, and are preferred more often by users who have technical experience. Flowcharts are used in procedure writing.

Secondary Formats

There are also four secondary format types: question and answer, troubleshooting, matrix table, and list.

Secondary formats are usually used within primary formats, but they sometimes show up on their own as a primary format for a document.

• A question and answer format is used to answer questions that may typically arise by the users, and are often written informally. This format can be used in both policies and procedures.

• Troubleshooting is found most often in procedure writing to help users quickly find the information they need so they can solve the problem as soon as possible, bypassing the need to read through the entire document again. Troubleshooting formats handle exceptions, or “breakdowns” of the typical processes described in the document.

• The matrix table format uses X and Y coordinates in a table to show which action should be taken at the rise of a specific problem. Campbell believes matrix tables are good to use when “readers need to refer repeatedly to the information periodically over time.”

• List formats are to be used frequently according to Campbell. Lists consist of short line lengths, wide margins, and clearly labeled, organized information. Some formats are more effective for certain types of writing than others. For example, Campbell mentions that if we are writing about our company’s commitment to safety, a standard narrative format should be effective. However, she continues, detailed procedures tend to work better in a playscript or flowchart format. It is also possible to (as noted above) combine formats. “Use your imagination and dabble with the possibilities,” Campbell says.

• A Hybrid Format is a combination of more than one format. In this example, we have a playscript combined with a flowchart. One warning here is that we should be carful not to over-clutter our documents with too many different visual formats.

So which formats are the best? It depends.

For policies, narratives, outlines, lists, and question and answer formats work well. Procedure documents can contain playscripts, flowcharts, troubleshooting, lists, question and answer, and matrix tables. Use common sense. If the format doesn’t contribute to the understanding of the user, it is probably best to select a different one (or more).

Source: Campbell, Jill. Writing Effective Policies and Procedures, 1998

Writing technical documents is not the same as writing a creative love story.  Forget about how her hair swept gently across her tanned shoulders as the sun parted slowly over the illuminated horizon.  We communicate to people with limited time inside businesses with limited resources.  Our Users need the information now; they need to know how to perform, or how to solve the problem right now!  So quit trying to impress your audience and learn how to write concisely.

Writing For Speed, Writing For Clarity

Remember back in high school when we were often told to write to a certain word count or page length?  I became aware that some students employed little tricks: changing the font to Arial or Veranda, or increasing the font size to 12.5 (which makes quite a difference in page length when used over hundreds of words).  At some point, it becomes silly to continue redundantly expanding on an issue already adequately addressed.

The key to remember in technical writing is to keep your writing simple.  Why force the user to read two sentences when they can receive the information in one?  Why complicate sentences with difficult wording when a straight-forward and clear message can help reduce confusion?  Try to imagine your audience in front of you.  How would you verbally communicate your message in that situation?  Now write it down.  Eliminate those formalities that were forced on us as teenagers and cut out words that only add length, but not clarity.

An example:
The technical communicator will then collect the assigned program surveys from the present users.
The technical communicator will collect surveys from users.

Which sentence would you rather read as a user looking for fast information?  The first sentence is too wordy to be included in a technical document.

But before you begin cutting apart your sentences, be certain that you are continuing to communicate the same information.  Sometimes sentences need a word that may initially appear to be only a “filler.”

An example:
Return the completed report in ten days.
Return the completed report in ten working days.

These sentences convey two different meanings.  In this case, “working” should remain in the original sentence.

10 Tips For Technical Communication Writing

1) Use simple words and phrases (by, not in accordance with)

2) Restrict most word usage to one or two-syllables (use, not utilize)

3) Eliminate long, drawn-out sentences (since, not in view of the fact that)

4) Say goodbye to redundancies (absolutely critical)

5) Write short paragraphs (100 words or fewer; 40 or fewer in procedures)

6) Consider one-sentence paragraphs (They are sure to grab the user’s attention)

7) Lists are awesome (Lists keep content short and clear while increasing white space)

8) Use an active voice (Start the motor, not The motor should be started)

9) Start with an action to be taken (Run the race, not The race should be run)

10) Use present tense (The employee reports the infraction, not The employee will report the infraction)

Use Specific Language

Finally, we should communicate specifically so that users do not become confused by our writing.

An Example:
The book may fall if not placed on a flat surface.
The book must be placed on a flat surface for stability.

Compare the word “may” against “must.”  The user will have no questions if they must do something.  May implies that the action is optional.  Watch out for these words: “may, might, could, should, ought to, probably, usually” (Campbell, 1998).  Each is different and has its own meaning.

We should all be aware that a company policy is a guideline that regulates organizational action, “controlling the conduct of people and the activities of systems (Campbell, 1998).” Procedures are simply the instructions for executing the company policies.

It may initially seem wise to craft very specifically written policy and procedure statements for nearly every conceivable action within the control of the company. However, as a little extra contemplation might discover, this would be highly impractical and inefficient. Even if this were attempted, by the time the writer felt they were “finished,” so much time would have passed that much of what was written to begin with is now irrelevant! As a result, new policies and procedures would need to be written.

Ambiguity In Policies

In many cases, the majority of policies in the workplace are fairly specific and easily-understood statements of what is (or is not) to be done by employees. However, no writer of policies will ever be able to anticipate, nor record in detail every situation that could arise… if only people were that predictable (might make for a boring life, but at least we would be prepared)! The reality is that a policy can really be anything that establishes a guideline.

“It is our policy to be the best in the business.” It is easy to see that this is quite an ambiguous policy!
But take, for an additional example, a policy that states, “Employees may not wear jeans containing a hole in them during casual Fridays.” Try to imagine, for a moment, all of the different ways that employees may interpret, and then try to “bend” this rule. I may not, as an employee, be able to wear jeans, but can I wear khakis containing a hole? Could I wear a pair of jeans with multiple holes? What if I am a contractor; must I abide by these rules when in the office? Keep in mind that this does not mean there should be no policies lacking ambiguity.

“It is our practice to bill within ten days of delivery.”
“Any accident involving more than $100 in damage will be considered a serious infraction.”
The above policy statements are simple, easy to understand, and to the point.

In Nancy Campbell’s book “Writing Effective Policies and Procedures,” she asserts that there are three factors that influence the extent to which policies should be ambiguous:
1) The ability of the readers (generally employees) to understand and cope with the policy.
2) Company management’s ability to understand and to enforce the policies.
3) The intensity of the issue addressed in the policy, and the organization’s commitment to control it.

Ambiguity In Procedures

Since procedures are the “how to” of policies, they tend to be less ambiguous. There are some reasons that we may want to maintain a degree of ambiguity here though as well. An example of a good situation may be when a policy needs to be written which instructs employees to use their professional judgment to assess a situation. They might need to gather information and then apply it towards a problem that could be difficult to strictly define.

Subjectivity In Policies And Procedures

As long as there are differences between individuals, there will always be some degree of subjectivity in existence. Even when we may try to be as objective as possible, someone will come along and often be able to point out how one may interpret our ideas differently.

Is the goal then to hire employees with company-aligned interpretations? There may actually be some truth to this thought. All companies want its employees to act professionally and to exercise sound business judgment. Again, Campbell believes there are three things to determine when thinking about subjective interpretations in a policy or procedure:
1) Which areas legitimately require employees to exercise some sound judgment.
2) How much subjectivity is needed.
3) How should we determine the basis for making that judgment.