Learn Technical Writing in Two Hours per Week

[Pages:18]Learn Technical Writing in Two Hours per Week

Norman Ramsey Harvard University

October 25, 2006

Preface

You may have difficulty writing, or you may have heard from professors or reviewers that your writing is hard to follow. Or you may have studied writing only in the context of literature, and have trouble translating your skills into a technical setting. Enough students have these difficulties that I have invested significant effort in helping students become comfortable, fluid, clear technical writers.

This booklet explains how to study technical writing in the context of a weekly group. If nothing else, a group will show you that you are not alone in your difficulties. Problems you may have are problems that others also have, and you can find similar problems even in published papers. But we do not emphasize problems; instead we emphasize useful principles and practices that you can learn to apply to your own manuscripts.

? I emphasize principles that can be applied successfully by a beginning writer. Especially for students in science and engineering, a principle is easily applicable when there is a simple, experimental way to decide if the written words obey the principle. (For example, I do not try to teach "omit needless words," because I know of no simple way to decide if a word is needless.) In this approach, I have been greatly influenced by Joseph Williams (1995).

? I emphasize practices that have been shown, again by experiment, to lead to productive writing. For example, I explain the difference between "binge writing" and "brief, daily sessions." In this approach, I have been greatly influenced by Robert Boice (2000).

What both approaches have in common is that even a beginner can apply a simple test to see whether he or she is applying a given principle or following a given practice. I hope this "engineering" focus on testable ideas will help you with your writing.

Norman Ramsey Cambridge, Mass.

Contents

1 Why a group and what might happen

3

1.1 Techniques for study . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Expected outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Mechanics and pragmatics

5

2.1 Expectations: preparation and meeting . . . . . . . . . . . . . . . 5

2.2 Commenting on a text . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Principles, practices, exercises, and guidelines

7

3.1 Principles and practices for technical writers . . . . . . . . . . . . 7

3.2 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.3 Supplementary guidelines . . . . . . . . . . . . . . . . . . . . . . 14

2

1 Why a group and what might happen

Compared with individual instruction, a writing group is not only more comfortable but also more effective. The focus is not relentlessly on your own writing. You see other writing at your own level as well as professional writing. In this context, you can evaluate the utility of the principles we teach and decide for yourself what does and does not work. Engineering is all about carefully evaluating techniques to see what works in practice, and you can apply that attitude to writing.

A group also helps because it's easier to learn to improve other people's writing before trying to apply the same principles to your own writing. You will also learn when your work is read by the group. It is invaluable simply to sit back and see where readers do not understand; miss the point; or feel distracted, bored, or confused. One reader's reaction might be idiosyncratic, but when a whole group of readers reacts the same way, it is easier to accept that the flaw might lie in the text.

The rest of this section gives a short overview of the material you may study in the group, as well as some things you can expect to happen.

1.1 Techniques for study

The primary purpose of this group is to learn good technique, as summarized by the principles and practices in Table 1 on page 8. A principle describes some property of a text; I try hard to phrase each principle so that you can easily decide whether a particular text respects it. You can then evaluate the hypothesis that a text which respects the principle produces a better effect in the reader's mind.

The practices focus not on properties of texts but on the means by which texts are produced. A practice recommends a behavior that, when followed by the writer, can lead to more fluent and successful production. It is unfortunately quite difficult for a single student to evaluate which practices make a difference, but you may get a chance to read about and discuss some of Robert Boice's (2000) controlled experiments, which are quite convincing.

1.2 Expected outcomes

Groups vary, but there are certain things you can expect to happen:

? You can expect your writing to improve, and perhaps to come more easily. Some of the exercises in Section 3.2 are simple enough that you will see results immediately.

? You will learn a few principles, and you will learn to apply those principles, but you will probably find it easier to apply them to others' work-- repeatedly--before you can apply them to your own work.

3

? In a 90-minute meeting, you will be able to discuss a surprisingly small amount of text. Don't be disappointed; a narrow focus (even just a few sentences!) often yields the deepest insights.

? Even when the focus is very narrow, discussions will often be great fun. ? Your first meetings will probably focus on mechanics. But after a month

or two, you can expect discussions of mechanics to lead to discussions of ideas. As your group gains experience, you will move more often (and more quickly) towards ideas. ? Most of the time, you will probably prefer texts which respect the principles in Section 3.1. But you may encounter one notable exception: there are texts that readers like, but that completely disregard Williams's advice about subjects and verbs (Principle 3). Such texts tend to be technical description, in which it is hard to identify any real actions taking place. ? You will be able to learn a lot about writing in two hours per week; you should be able to leave each meeting feeling you understand something significant about your own and others' writing. ? In a semester, you will probably find it difficult to learn more than just 2 or 3 principles or practices--and even that much will be hard work. But if you really internalize 2 or 3 useful principles and consistently apply them to your own work, you will be impressed at how much better your writing gets.

4

2 Mechanics and pragmatics

2.1 Expectations: preparation and meeting

Our goal is to teach technical writing in two hours per week: half an hour of preparation and an hour and a half of meeting. (Experienced students really do prepare in half an hour, but beginning students spend more time both on exercises and on supplementary reading.) Attending the meetings is important; unlike other kinds of knowledge, which can be acquired independently from a text or by listening to a taped lecture, writing can really only be learned by doing and by getting feedback. If you don't show up, you learn nothing, and if you don't comment on others' work, it's unfair for you to benefit from others' reading of your own work.

Meetings about principles Most meetings will focus on principles of clear writing. A meeting focused on a principle will probably be organized around an exercise that you will have completed before the meeting. Each exercise requires analysis, and sometimes revision, of a sample text written by a student author or by a professional. A typical exercise focuses on just a few paragraphs, or at most a section. The exercises might remind you of problem sets, except that because they often call upon you to evaluate events that happen in a reader's mind, not everyone will agree on the answers.

Meetings about practices Some meetings will focus on practices of successful writers. A meeting focused on a practice will probably be organized as a discussion of some reading. The discussion may resemble discussions in graduate seminars. The most effective discussions analyze how the ideas in a reading might apply to your own writing practices.

Early meetings For the first few meetings, I like to analyze professional papers. Such papers provide a good platform for testing our principles scientifically: Do the writers we like respect our principles? With what effects in the minds of the readers? I will enlist your help by inviting you to bring examples of published papers you like and dislike.

2.2 Commenting on a text

A key part of our approach is to ensure that group members' comments support empirical evaluation of a text. Here are some examples of useful comments:

? "I believe that the most important idea in the paper is the idea of using a finite automaton to model the infinite space of possible signatures."

? "At the end of paragraph A, I was happy, but but the time I got to sentence 3 of paragraph B, where it says that a machine register has a weight that is equal to the number of resources it consumes, I felt that I no longer understood what was going on."

5

? "I don't understand the distinction between an `argument' and a `parameter'."

Each of these examples provides evidence of important events happening in the reader's mind, and two of them tie those events to specific words or locations in the text.

An example of a less useful comment is "the third section is not well written." The comment is about the text, not about what is in the reader's mind, and it is not focused on any particular part of the text.

When your paper is being discussed, we may ask you not to speak. In part, we do this to be sure that any comments are made in response not to you but to the words on the page. In part, we do it to mimic the process of professional reviewing; after all, when you send a paper out for review, you can't enter into a discussion to explain what you really meant. And in part, we do it to give you space to focus your full attention on what your readers are saying, without being distracted by thinking about how to formulate a response. You'll get a chance to talk at the end of the session.

When your text is being discussed, we encourage you to take notes. It is surprisingly difficult to remember what is said; no matter how sympathetic the group and how mature the author, there is something intense and sensitive about having one's work discussed. The intensity of the experience can make it hard to hear and remember everything as it is being said. If your group members agree, you may even wish to use a microphone to record discussions, especially if you are getting comments on a paper that you will soon submit.

6

3 Principles, practices, exercises, and guidelines

This section sets forth what you will actually study: principles, practices, and guidelines for successful writers, together with exercises that will help you master the principles. The principles and practices are listed in Table 1 on page 8. I introduce them with short explanations of the thinking behind them, but neither the principles nor the practices are self-explanatory. Explanations can be found in Williams (1995), in Boice (2000), and also in the exercises.

3.1 Principles and practices for technical writers

Principles A principle is useful only if a beginning writer can test to see if a text obeys it. Here are some examples of principles that are difficult to test for (all real advice from real writers):

? Omit needless words.

? Pay attention to the rhythm of the paragraph.

? Group ideas into sentences in the most logical way.

Here are some principles that are easier to test for:

? The agents and actions that you want to appear most important in the mind of your reader should be used as the subjects and verbs of your sentences.

? The old information in a sentence should appear at the beginning, and the new information should appear at the end.

? Don't use different words to mean the same thing, especially for technical terms. For example, don't use both "stack frame" and "activation record."

? In technical text especially, prefer singular to plural. For example, in the sentence "lexical analyzers translate regular expressions into nondeterministic finite automata," how will you know if a single lexical analyzer translates one expression or many? Singular is clearer.

By using testable principles, we stay within the educational culture of science: for each principle, you can test the hypothesis that applying the principle makes writing clearer.

The principles in Table 1 are organized more or less by scale; in general, earlier principles apply to smaller parts of a manuscript. I have starred principles that I consider especially valuable.

Practices It's surprising how many books on writing talk only about the words on the page and not about what the writer is actually doing--how the writer behaves. These books are missing many important questions: Where do you write? When? How often? For how long? With what goals? How do you

7

Principles

0. Correctness. Write correct English, but know that you have more latitude than your high-school English teachers may have given you.

1. Consistent names. Refer to each significant character (algorithm, concept, language) using the same word everywhere. Give a significant new character a proper name.

2. Singular. To distinguish one-to-one relationships from n-to-m relationships, refer to each item in the singular, not the plural.

3. Subjects and verbs. Put your important characters in subjects, and join each subject to a verb that expresses a significant action.

4. Information flow. In each sentence, move your reader from familiar information to new information.

5. Emphasis. For material you want to carry weight or be remembered, use the end of a sentence. 6. Coherence. In a coherent passage, choose subjects that refer to a consistent set of related concepts. 7. Parallel structure. Order your text so your reader can easily see how related concepts are different

and how they are similar. 8. Abstract. In an abstract, don't enumerate a list of topics covered; instead, convey the essential

information found in your paper.

Practices

1. Write in brief daily sessions. Ignore the common myth that successful writing requires large, uninterrupted blocks of time--instead, practice writing in brief, daily sessions.

2. Focus on the process, not the product. Don't worry about the size or quality of your output ; instead, reward yourself for the consistency and regularity of your input.

3. Prewrite. Don't be afraid to think before you write, or even jot down notes, diagrams, and so on. 4. Use index cards. Use them to plan a draft or to organize or reorganize a large unit like a section

or chapter. 5. Write a Shitty First Drafttm. Value a first draft not because it's great but because it's there. 6. Don't worry about page limits. Write the paper you want, then cut it down to size. 7. Cut. Plan a revision session in which your only goal is to cut.

Table 1: Principles and practices of successful writers

8

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download