ITS 311: IT Communications

Chapter 2: Executing the Writing Process: Theory and Practice

Objectives:

This chapter begins the discussion of actual writing skills and conventions. Objectives important to this chapter:

1. Basic Communication Theories
2. Collaborative Writing Strategies
3. Audience Behavior and Reception
4. Prewriting, writing the draft, and post writing

Concepts:

Introduction

Chapter 2 begins the discussion of effective writing techniques. Two rather different methods are described first:

• Rhetorical method - This method may have been developed by the Greek philosopher Aristotle. It features the use of rhetorical questions posed to an audience, questions that are meant to lead the listener/reader from a known point of view to the point of view promoted by the presenter. This method requires that the presenter know the audience, and modify the presentation to fit the attitudes, knowledge, and needs of that audience.
• Bell Telephone Laboratories method - This method treats any communication like a signal that will be transmitted to a receiver. It is analyzed in terms of eight related aspects.
  • Sender - the presenter of the message
  • Receiver - the intended audience
  • Message - the content; the actual information you are presenting
  • Channel - the transmission medium, such as print, e-mail, or web site
  • Noise - anything that contributes to misunderstanding, such as bad print quality, poor electronic reception, or poor choice of language
  • Encoding/decoding - the actual words and symbols used, the layout of a document, the fonts, colors, and graphics chosen for the message
  • Interpretation - the reaction and degree of understanding achieved by the audience
  • Feedback - information about the message from the audience, which may be direct feedback, or indirect (such as an increased or decreased number of help desk calls)

Both theories support the idea of knowing the audience well. In practice, this is not always possible. For example, I have not yet met the class members these notes are being written for, but I can still write them with the needs of most students in mind. In general, a writer creates a work with an audience in mind, even if that audience is a loosely defined one. In the case of technical writing, the audience is assumed to be people who want to know something about the subject the work is about.

The author discusses some differences between writing alone and writing as part of a team. There are advantages to teamwork, especially if you have the luxury of being able to recruit or select team members who have complementary skills. Practical experience will not always match the ideal situation, which leads to a lesson for the course: you may have to carry out an entire job yourself, to become acquainted with all of its tasks, even if you are not an expert at all of them. Case in point, any episode of Dirty Jobs.

Some reasons to recommend working as a team:

• Two sets of eyes see more than one set of eyes. This is true for discovering how software and hardware work, and it is true for proofing and troubleshooting each other's work.
• The more people on a team, the more likely there will be a wider range of skills on that team to apply to the project.
• If skills are similar, more people can divide the work of a large project, and finish it faster than one person.

Some potential problems can arise when working on a dysfunctional team:

• Real or perceived differences in the work load assigned to team members can lead to bickering, resentment, and lack of cooperation. Any of these results can lead to lower quality work, and missed deadlines.
• Collaborations require communication, editing, and rework to match style. This will generally take a significant amount of time.
• Groups can be dominated by strong willed members, which can lead to the other team members not contributing as much as they might have. A strong leader is needed to make sure that all contributors are adding value, and that alternate points of view are not lost to the process.

A technical writer will create a more focused work if the audience's knowledge about the subject is known to the writer. Knowledge of where to start lets the writer skip lessons or directions that are familiar to the audience. Likewise, if the writer knows that the audience is familiar with common technical terms, those terms need not be defined before they are used in the work. It is best practice, however, to define any term that is not considered to be in general use. If the audience will vary greatly in technical knowledge, the work should begin by defining basic technical terms, and build from there.

In addition to avoiding undefined technical terms, a writer should also avoid using words and phrases that are likely to be misinterpreted by the audience. The author gives some examples of common English words that mean different things in different countries. For example, a torch may be a stick that is on fire on one end, or it may be a flashlight. Likewise, American and British spelling differ for some words, but most of these are easily understood by readers of either background. I have used the word author several times. Had I spelled it authour instead, I trust Canadian and British readers might have felt more at home, and American readers would still have understood. Our author, in fact, assumes that a given reader will not have any knowledge of such differences. She may not be giving the general reader enough credit. Assume that your readers will have some experience. Have several people proof read your work and listen to suggestions that improve it.

The author turns to the topic of a writing plan, suggesting that you may want to divide the process into three large phases: prewriting, writing a draft, and post writing.

Prewriting

Before you begin to write, you should decide what you are going to write. Consider using each of Rudyard Kipling's six honest serving men to describe your project:

I keep six honest serving-men
(They taught me all I knew);
Their names are What and Why and When
And How and Where and Who.

What are you writing about? Who are you writing for? Why are you writing it and why will they read it? How will you create your work, and how will it be delivered? When and where will your output be used?

When you have answered these questions, you should have a topic and a tone to take in the work. Now, you need a plan. Making an outline is recommended. It is not often done for short works, but it still recommended. Making an outline can help you notice that you have left out a necessary or desirable topic. It can also help you to organize your work, and to cut unnecessary material.

Writing

When writing a draft, the author recommends choosing between an inductive and a deductive presentation. An inductive presentation presents a series of facts, or proofs, followed by a conclusion. A deductive presentation is the reverse: it presents a conclusion first, and it follows the conclusion with evidence. In some grammar classes, the conclusion is called a topic sentence. This is true whether it comes at the beginning or end of a paragraph.

The author recommends the deductive approach. This tells the reader what your point is right away, and gives you the opportunity to prove that point. This approach is less boring for the reader, who might lose interest if several long proofs come first. It is sometimes useful to combine the two concepts: present your conclusion, present your evidence, and present a summary.

The author makes some recommendations about style and tone. Remember to be truthful, impartial, and simple. Do not become emotional or judgmental. The purpose of technical writing should be to inform, not to incite an emotional response.

Another point is to be precise. If you are writing about the heat of laser printer fusers, don't just say they get very hot. Say their temperature typically reaches 200 degrees Celsius (392 degrees Fahrenheit). Get the facts your readers need, verify their accuracy, and provide those facts. In this example, a statement of the temperature involved provides a much clearer warning than the vague idea of "very hot".

Another point worth remembering is to be brief. If you are being paid by the word, it is tempting to add more words than you really need. It is tempting to some people to write more so that their presentations run longer. Do your readers and listeners a favor: omit needless words. Follow that link, by the way, to the Wikipedia article on a book you need to read: The Elements of Style. If you are going to be a writer, you need to own a copy. If your local bookstore does not have it, look for it in an online store. Over the years, many students of English grammar, literature, and composition have been compelled to read it, and have improved their work by following its guidelines. It is an indispensable tool. If you have any love for the English language, it is also a joy to read.

The author recommends writing in the active voice rather than the passive voice. That last sentence is written in active voice. Rewriting it in the passive voice would look like this: The active voice is recommended by the author, over the passive voice. See the difference?

• Active voice: someone does something
• Passive voice: something is done by someone

Active voice is typically shorter, but that is not the reason you may prefer it. Active voice emphasizes someone doing something. Passive voice emphasizes the act, not the actor, the object of the sentence, not the subject.

Postwriting

The author gathers several tasks into this phase of the project that could just as well be done in the writing phase. Revision for spelling and word choice should be done as a document is being written, but they may also be done by an editor in this phase. A word of caution: the editor of a technical document should understand the message of that document. If the editor is not a technical editor/author, that editor may damage the document by changing a word or two.

The author makes a good point about signal words, but her explanation may be a bit unclear. She is recommending that you add words to your paragraphs to make them flow. Words that give a sequence (e.g. first, second, third, next, finally) are especially helpful, since they help the reader follow a procedure without missing steps. Cue words that show similarity or contrast emphasize specific points. Words that show summarization mark the end of a discussion, allowing the reader to draw a mental box around your idea.

Several pages are devoted to grammar problems. Again, I recommend reading The Elements of Style to avoid these errors, and referring to it often when correcting them.

The author ends the chapter by returning to the Bell Telephone Laboratories model. Much of the discussion above is about the message. She now discusses the remaining model aspects.

The channel should be considered at the outset, not at the end, but the model places channel issues here. The question is how to send the message to the receivers. Should it be printed, shown as a PowerPoint show, put on a web site, made into a movie, or should some other method be used?

Noise issues include problems with transmission of any type. Is the copier making clear copies? Is the web site accessible to all intended viewers? Are the tapes we are sending out of good quality? The author points out that noise issues can also come from audience misunderstanding. Also, audience reaction to the presentation can lead to noise. My wife likes to watch a cable channel that does nothing but sell jewelry. This channel contains a great deal of noise for me, since I am not interested in the subject matter, and I do not find their presentations well done. Conversely, my wife enjoys those presentations, so there is no noise for her.

Encoding/decoding issues are those that arise if the audience does not find your message easy to understand. The author recommends several ways to make your message more understandable:

• Use white space liberally. Break long paragraphs into several shorter paragraphs.
• Omit needless words.
• Use headings to help the reader find desired sections of the message.
• Use bold, italic, or special characters to draw attention to text.
• Use bullets to draw attention to lists. Use numbered lists when the items in them are meant to follow a sequence.
• Use graphics to make instructions clear.

Interpretation issues are caused by the audience misunderstanding your message or being unsure of your meaning. As noted elsewhere, many words have multiple meanings. Seek to be clearly understood, leaving no doubt about your message.

Finally, solicit feedback from your users. This should be done with your proofreaders and your editor, but also with the audience. Technical documents are typically revised over and over. User feedback will help you improve each new version.