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.

And perhaps more importantly, how can you benefits from using one?

Have you ever had a teacher stand up in front of the chalk board and just write the ideas of their students? Or maybe you’ve watched as co-workers used sticky notes for idea generation, or family members who jotted notes into their notepads.

Use Mind Maps For Creative Brainstorming

I was introduced to mind mapping software through a recommendation from a student in my technical documents and procedures class a few weeks ago. Her specific recommendation was for the VUE: Visual Understanding Environment… and after playing around with some of the other free mind map software, I have to support that recommendation!

If you’re tired of having to deal with all your scribbled-on paper, use VUE to keep your thoughts organized. VUE is extremely easy to use, and it looks great too. A few days ago I felt ready to begin thinking about a few new web projects. Take a look at my most recent brainstorming session.

You can use this program for recording just about any set of creative thought processes. Technical communicators can especially benefit during the prewriting stage of document writing. While most people use lists to hold their ideas, lists do not easy adapt to a branching, creative mindset. using a list instead of a mind map could mean the omission of important considerations if one is not careful.

Some of the other free programs I examined include: Xmind and FreeMind.

Only a few days ago Gartner, Inc., a world leader in information technology research, made five bold predictions regarding the direction of social media that could significantly impact the role of technical communicators if time proves them to be correct.

“A lot has happened in a year within the social software and collaboration space. The growing use of platforms such as Twitter and Facebook by business users has resulted in serious enterprise dialogue about procuring social software platforms for the business,” stated Mark Gilbert, vice president of research at Gartner. “Success in social software and collaboration will be characterized by a concerted and collaborative effort between IT and the business.”

E-mail Will Be Replaced

As early as 2014, Gartner predicts that social networking services (Facebook, Myspace, LinkedIn, etc.) will become the primary way of communicating within the company for about 20 percent of businesses. These social network sites will become the “hub” of business activity, and allow for interaction with their clients through the use of employee-created social networking accounts specifically to be used for business communications.

Interestingly, rumor has it that Facebook has already begun working on this project.

Twitter For Businesses?

More than 50 percent of enterprises are said to be participating in “microblogging” by 2012. When you think of microblogging, think “tweets” from Twitter: short status updates to aid in communicating in-the-moment information. Most businesses will be using an internal, more secure and potentially customized version of a Twitter-like service, while we’ll only find 5 percent of businesses participating in this form of communication outwardly to the clients and shareholders.

Social Media Initiative Failures

Over 70 percent of IT-initiated social media initiatives will fail; 50 percent of those initiated by the business-side won’t reach success either. ” IT organizations are accustomed to providing a technology platform (such as, e-mail, IM, Web conferencing) rather than delivering a social solution that targets specific business value,” Gartner asserts, “Enterprises will need to develop entirely new skill sets around designing and delivering social media solutions. Until this happens, failure rates will remain high.”

What do you think this prediction means for technical communicators? It looks to me that we’ll have some decent job security in this area as long as employers are able to recognize the (often) intangible value we can bring to their business.

Smartphone Software Will Influence PC Application Design

“70 percent of collaboration and communications applications designed on PCs will be modeled after user experience lessons from smartphone collaboration applications.” With cell phones having such a large market penetration rate, users are able to now communicate with more people in less time than they can using their PC at home. As a result, PC software will begin to take more of its influence from handheld-based applications within the next 5 years.

Businesses Are Reluctant To Ask Permission For Data

Only 25 percent of enterprises will utilize social network analysis on a regular bases through 2015. With recent news of Facebook and other such companies collecting detailed information on users without expressed permission, Gartner estimates that privacy issues will still be a major concern for the majority of internet users. However, if businesses are able to obtain this permission to improve targeting of products and services to potential customers, both performance and productivity can increase.

Read the official press release here.

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.

Recently in my Technical & Scientific Prose class, we were assigned to read through and analyze 15 popular poems by Robert Frost, the last century’s most popular American poet.  By the time most of us graduate high school, we almost certainly have been exposed to a few of his shorter and (seemingly) less metaphoric work, including “Fire and Ice,” and “The Road Not Taken.”

Even while I have never taken an especial interest in poetic writing, I have found that I do enjoy much of what Robert Frost has written, not for his particular writing styles, but for the timeless concepts that has been found consistent among those I read from him.  And for this reason, Robert Frost poems will continue to be read in schools and by the public.  His messages are inherent to the human condition, they never expire:  Fear, compromise, hatred, friendship, and my favorite: the passage of time.

After reading through the poems and writing an analysis on each, I was also instructed to select the one that I most enjoy and share my thoughts with the class.  I chose “Stopping by Woods on a Snowy Evening.”  This is a simple poem, but important in my mind because the pace of society has often caused us to miss out on the small benefits and joys of life as we place  focus on our careers, education, and families.

Whose woods these are I think I know.
His house is in the village though;
He will not see me stopping here
To watch his woods fill up with snow.

My little horse must think it queer
To stop without a farmhouse near
Between the woods and frozen lake
The darkest evening of the year.

He gives his harness bells a shake
To ask if there is some mistake.
The only other sound’s the sweep
Of easy wind and downy flake.

The woods are lovely, dark and deep.
But I have promises to keep,
And miles to go before I sleep,
And miles to go before I sleep.

I recommend reading through some of his work!  A few other poems of interest include: “A Patch of Old Snow,” “Birches,” and “On Going Unnoticed.”