Chapter 2 begins the discussion of effective writing techniques. Two rather different methods are described first:
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:
Some potential problems can arise when working on a dysfunctional team:
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.
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
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.
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 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.
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:
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.