Docsity
Docsity

Prepare for your exams
Prepare for your exams

Study with the several resources on Docsity


Earn points to download
Earn points to download

Earn points by helping other students or get them with a premium plan


Guidelines and tips
Guidelines and tips

Editing Principles and Practices for Technical Writers: A Study Guide, Lecture notes of Technical Writing

An overview of editing principles and practices for technical writers. It includes explanations of key principles, working practices, and exercises to help master the concepts. The principles cover subjects such as subjects and verbs, information flow, and mindfulness during the writing process.

Typology: Lecture notes

2021/2022

Uploaded on 09/12/2022

lumidee
lumidee 🇺🇸

4.4

(47)

364 documents

1 / 22

Toggle sidebar

This page cannot be seen from the preview

Don't miss anything!

bg1
Learning Technical Writing
Using the Engineering Method
A Handbook for Groups
Norman Ramsey
Tufts University
August 2016
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, fluent, 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—engineering heuristics—that you can learn to apply to your own
manuscripts.
I emphasize principles that can be applied successfully by a beginning writer. Es-
pecially 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
Medford, Mass.
pf3
pf4
pf5
pf8
pf9
pfa
pfd
pfe
pff
pf12
pf13
pf14
pf15
pf16

Partial preview of the text

Download Editing Principles and Practices for Technical Writers: A Study Guide and more Lecture notes Technical Writing in PDF only on Docsity!

Learning Technical Writing

Using the Engineering Method

A Handbook for Groups

Norman Ramsey

Tufts University

August 2016

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, fluent, 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—engineering heuristics—that you can learn to apply to your own manuscripts.

  • I emphasize principles that can be applied successfully by a beginning writer. Es- pecially 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 Medford, Mass.

Contents

  • 1 Why a group and what might happen
    • 1.1 Techniques for study
    • 1.2 Expected outcomes
  • 2 Mechanics and pragmatics
    • 2.1 Expectations: preparation and meeting
    • 2.2 Commenting on a text
  • 3 Principles, practices, exercises, and guidelines
    • 3.1 Principles and practices for technical writers
    • 3.2 Exercises
    • 3.3 Supplementary guidelines
  • 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 princi- ples, but you will probably find it easier to apply them to others’ work— repeatedly—before you can apply them to your own work.
  • In a 75-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 a few hours per week; you should be able to leave each meeting feeling you understand something significant about your own and others’ writing.
  • In one 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.

2 Mechanics and pragmatics

2.1 Expectations: preparation and meeting

I have found it ideal to meet once a week for around an hour and a half each time. And preparation is imperative; when students begin, they may need an hour or two for exercises and another hour or two for supplemental reading. But by the end of a year’s study, almost every student can prepare in under an hour. 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 editing principles Most meetings will focus on a principle of clear writing and on its application to editing a text. A meeting focused on a prin- ciple will probably be organized around an exercise that you will have completed before the meeting. Each exercise requires analysis, and sometimes editing, 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 re- mind 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 working practices Some meetings will focus on a working practice observed in successful writers and on the group’s own experience with the practice. A meeting focused on a practice may 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. There is a better way to organize a meeting about practices, but it requires preparation in advance: keep a notebook that records data about how you tried to use a practice and how it affected your productivity. Analysis of the data will reveal not only what works, but even more important, how to make it work.

Early meetings For the first few meetings, I like to analyze professional pa- pers. 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.”

I tried to integrate research into the ways readers read with my experience working with professional writing in a variety of fields, in order to create a system of principles that would simultaneously diagnose the quality of writing and, if necessary, suggest ways to improve it. — Joseph Williams, Style

3 Principles, practices, exercises, and guidelines

This section sets forth what you will actually study: editing principles, working 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

Editing principles An editing 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 nondeterminis- tic finite automata,” how will you know if a single lexical analyzer translates one expression or many? Singular is clearer.
  • To clarify the meaning of mathematical or terminological definitions in which no action is taking place, illustrate the definitions with plentiful examples.

By using testable principles, we stay within the educational culture of science and engineering: 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.

Editing principles

  1. 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, verbs, and objects. Put your important characters in subjects, and join each subject to a verb that expresses a significant action. Understand what object, if any, is acted upon.
  2. Definitions. Mathematical definitions lack significant actions, so clarify them using examples. ⋆5. Information flow. In each sentence, move your reader from familiar information to new informa- tion.
  3. Emphasis. For material you want to carry weight or be remembered, use the end of a sentence. ⋆7. Coherence. In a coherent passage, choose subjects that refer to a consistent set of related concepts. ⋆8. Purpose. Give each paragraph a purpose, which is the effect you want in the mind of your reader.
  4. Paragraph = Issue + Discussion. Begin a paragraph with one to three sentences, which end by emphasizing the issue. Finish by using the issue in in coherent subjects or thematic strings.

⋆10. Parallel structure. Order your text so your reader can easily see how related concepts are different and how they are similar.

  1. Abstract. In an abstract, don’t enumerate a list of topics covered; instead, present the essential information found in your paper.

Working practices

⋆1. Pause mindfully, frequently. Mind your body, thoughts, and feelings—and the stage of your work. ⋆2. 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.

  1. 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.
  2. Prewrite. Before you write, think, talk out loud, and jot down notes, diagrams, outlines, and so on.
  3. Use index cards. Use them to plan a draft or to organize or reorganize a large unit like a section or chapter. ⋆6. Write a Shitty First Drafttm. Value a first draft not because it’s great but because it’s there.
  4. Don’t worry about page limits. Write the paper you want, then cut it down to size.
  5. Cut. Plan a revision session in which your only goal is to cut.

Table 1: Principles and practices of successful writers

Why include direct objects in Exercise A? Williams talks only about the agents (characters) and the actions they take, not about the objects acted upon. It may be that using agents and actions as subjects and main verbs is enough to help you construct good sentences. But when you are planning a larger work—say to describe a complex experiment or a system in which hardware, software, and people all play a role—getting a handle on the direct objects is invaluable. It’s common, for example, to find a character that is the agent of one action but the direct object of another action (the IDE controls the compiler but the user controls the IDE). It’s also common to find relationships in which there may be agency in both directions (the n-gram statistics direct the classifier and the classifier updates the n-gram statistics). Capturing the relationships in table (or even in a directed, labeled graph) is a first step toward explaining them clearly.

3.2 Exercises

The exercises below comprise most of what we do when I teach writing. Almost every exercise is designed to teach one of the principles in Table 1; an important exception is Exercise H, which although valuable, does not come with an articu- lated principle. Not all exercises are equally good; among the best are Exercises A, C, and H, which you can profitably do more than once. The exercises are listed in an order in which it may be useful to do them.

Exercise A: Who does what to whom This exercise is based on Chapter 2 of Williams’s Style: Toward Clarity and Grace. The big lesson from Chapter 2 is this: if you have certain ideas in your head about what agents and actions are most important, you will communicate those ideas most clearly if you make those agents and actions the subjects and verbs in your sentences. To help you learn how to apply this principle, here is an exercise in three parts. The first part is about the ideas that form in your head as you read, not about the words on the page. Take the text, and as you read each paragraph, identify

  • The important characters in the story
  • The actions taken by those characters
  • When applicable, the direct objects of those actions

Use your own words to identify the characters and their actions, not necessarily the words in the text. I recommend using a clean sheet of paper to create a table listing agents (who), actions (does what), and objects acted upon (to whom). The second part is to go through the text again. Make a distinctive mark on the main subject and verb of each sentence. (I like to underline the subject and double-underline the verb.) Whenever the main verb is a form of a light verb like “make,” “do,” “have,” “bring,” “put,” “take,” or especially “be,” make a distinctive mark in the margin.

The third part is to compare. How consistent are the important characters and actions with the subjects and verbs used in the text? If you felt good about the text and enjoyed reading it, did you find that the characters and actions were consistent with the subjects and verbs? If you didn’t enjoy the text, did you find that the characters and actions were inconsistent with the subjects and verbs? Did you find lots of light verbs?

Exercise B: Diction Sometimes it can be hard to work with agents and actions because the agents or actions are difficult to identify by name. Writing about research in computing can be especially difficult because there are so many new things for which there are no established names. To help with these problems, here are the three parts of Principle 1 (Consistent names):^1

  • Give it a name. Some writers try to dodge the issue by carefully avoiding naming things. Saying “our language,” “the prototype system,” or “the al- gorithm” doesn’t do the job. Do your reader a favor and give your language, your system, or your algorithm a name.
  • When you are talking about one idea, always use the same word or phrase. For example, don’t call your idea “data dispersal” in one place and “revealing secrets” in another.
  • When you are talking about different ideas, never use the same word. For example, don’t use the word “system” to talk about a model, an algorithm, and a software artifact.

The exercise is to scrutinize a manuscript and identify places where names are misused or an important thing is unnamed. Reduce the number of names as needed, and choose effective names for each concept, agent, action, and object.

Exercise C: Old and new information This exercise is based on material from Chapter 3 of Williams’s Style: Toward Clarity and Grace. The idea is to make text easier to read by considering the flow of information from one sentence to the next sentence within a paragraph. Williams argues that information flows best when old information is at the beginning and new information is at the end. To learn how to apply this principle, here is an exercise in two parts.

  • The first part is to go through the text and mark the old and new information in each sentence. If there is more than one piece of new information, mark the most important new information. I usually mark with a dotted underline for old information and a solid underline for new information, but you should mark using a system that works for you. Remember that although we look at each sentence in isolation, good informa- tion flow connects adjacent or nearby sentences. Often, the old information at the beginning of a sentence is the new information delivered at the end of the preceding sentence. And the new information at the end of a sentence becomes available to be used as old information in the succeeding sentence or sentences. To see a perfect example of how old and new information can be used to connect sentences so they flow smoothly, look at the sentences about the black hole on page 47 of Williams. (^1) All the examples are from papers we have discussed in my group.
  • When the first sentence of a paragraph doesn’t begin with a few words that seem to be a topic, look instead to the end of that sentence. If the end of the sentence introduces new ideas that are then developed in the rest of the paragraph, put a box around those new ideas.
  • When you study topics for coherence, include the boxed ideas on your list of topics.

Exercise F: Quick start Underline the first seven or eight words of each sen- tence. If the underlined portion does not contain an agent as subject and an action as verb, that sentence is a candidate for revision.

Exercise G: Issue and discussion This exercise is based on Chapter 5 of Williams’s Style: Toward Clarity and Grace. The idea is that a paragraph is divided into two parts. The paragraph opens with a kind of introduction or overture, which Williams calls the issue. The last sentence of the issue should end, in the position of emphasis, with the topic of the paragraph. That topic can then engender thematic strings that recur throughout the rest of the paragraph, which Williams calls the discussion. Thematic strings are especially effective when they appear as coherent subjects, but a thematic string may appear anywhere in a sentence. The clear emphasis at the end of the issue, coupled with the recurring thematic strings in the discussion, give your reader a strong sense of coherence and what the paragraph is about. The exercise proceeds as follows:

  1. Choose a paragraph and as best you can, draw a dividing line between issue and discussion. If you cannot find such a dividing line, write new sentences for the beginning of the paragraph, and draw the dividing line after your new sentences.
  2. Underline the phrase that appears in the position of emphasis at the end of the issue. In your own words, restate the subject, object, concept, idea, or theme embodied in that phrase.
  3. Throughout the discussion, underline each sequence of words that you think is thematically connected to the emphasized phrase at the end of the issue.
  4. Decide if you think the paragraph respects the principle. Decide how coher- ent you feel the paragraph is—that is, how much does the paragraph feel to be about one thing. Are the two correlated.

In the advanced version, revise:

  1. Choose another paragraph. Looking at what the paragraph is about, choose a set of thematic strings that (a) are all related and (b) can reasonably appear in the paragraph.
  2. Rewrite the issue, or write a new issue, to end in a phrase chosen from among those thematic strings.
  3. Rewrite the discussion to use the thematic strings.
  4. Compare the original with the revision, and decide if the original is improved. Ask your readers!

Exercise H: Structure of a section This exercise can help you with the structure of a section in a conference or journal paper or with the structure of a chapter in a thesis. The preparation is simple: each member of the writing group reads each paragraph of the section or chapter and answers two questions.

  1. What is the purpose of this paragraph?
  2. How well does it fulfill its purpose?

The first question is more important than the second. The hard part is distin- guishing the purpose of a paragraph from the content of that paragraph. Roughly speaking, content is what a paragraph is about, while purpose usually has to do with causing an event to happen in a reader’s mind. The group meeting needs a skilled moderator who can keep the group focused on purpose. The fun comes in the meeting. The author is not allowed to say anything. Instead, the text has to speak for itself. The writing-group moderator will help the group form its collective impressions of the paragraphs. You can expect a lot from this exercise.

  • It can be eye-opening for the author to learn how others read the text.
  • It can let the author know how successful the section is in general.
  • It can identify several kinds of structural problems:
    • Paragraphs that try to serve two or three purposes at once
    • Paragraphs the purpose of which is not obvious
    • Introductory material at the end of the section
    • Paragraphs serving the same purpose that are widely separated in the text
    • Redundant paragraphs

There’s generally no need to try to identify such problems in advance; these identifications emerge naturally from the discussion.

We’ve used this exercise successfully with sections of 10–20 paragraphs. After doing this exercise, it may be helpful to use a deck of index cards to reorganize the section (Practice 5).

Exercise I: Parallel structure Much of scientific writing is about making comparisons. When two or more complex things are compared, a reader can follow more easily if the comparison uses parallel structure. I encourage you to establish parallel structure as a two-part process:

  • You design a template for describing each thing to be compared. The fixed parts of the template are the same in each description; the variables vary.
  • For each thing you describe, instantiate the template by substituting text for the variables.

These two parts can be iterated in either order. Your job is to identify an effective template, but both designing the template and judging its effectiveness are easier if you look at instances. The exercise proceeds as follows:

The first category of time-varying data is regular, which usually involves a certain phenomenon that grows, persists, and declines in several (distinct) stages. The rate of change at each stage could vary dramatically in space and time. Many natural phenomena and their simulations, such as the earthquake, fall into this category. The second category of time-varying data is periodic. For this type of data with recurring patterns, special attentions are paid to space-time abnormal events. For example, climate data normally follow a daily, monthly, or yearly pattern. Oc- casionally, however, the data may also fluctuate out of expectation, creating an abnormality that requires attention or investigation. Finally, the third category of time-varying data is turbulent. A number of computational fluid dynamics (CFD) simulation data are turbulent, featuring the ubiquitous presence of spontaneous fluctuations distributed over a wide range of spatial and temporal scales

If you want to go deeper into sentence structure, Williams’s Chapters 8 and 9 show many examples of how large sentences can be structured, including using parallel structure. But be warned that I found these chapters more advanced and more difficult to learn from than the earlier chapters.

Exercise J: Singularity A common fault in computer-science writing is to use plural everywhere. In technical text especially, prefer singular to plural. For example, in the sentence “lexical analyzers translate regular expressions into non- deterministic finite automata,” how will you know if a single lexical analyzer translates one expression or many? Singular is clearer. The exercise is to tackle several paragraphs and eliminate as many plurals as possible (without changing the meaning of the text).

Exercise K: Cutting Many professional papers are limited to a fixed number of pages. To produce a paper within the limit, it is sometimes necessary to write a longer paper and then cut. Because it is so difficult to cut your own work, we sug- gest practicing cutting on someone else’s work. It might be useful to experiment with cutting a section to 34 or even 12 of its original length. Start this exercise with a section in which each paragraph has been labeled with its purpose, as in Exercise H. Use this information to decide how many jobs the section does within the paper as a whole. Based on this decision, cut in one of two ways:

  • If the section does multiple jobs, perhaps one or more of those jobs can be eliminated. In this case, identify the paragraphs doing the work, and cut those paragraphs.
  • Perhaps the section does only one job, or perhaps each of the jobs it does is essential. In this case, assign a relative value of each paragraph; an easy measure of value would be the ABC scale. Now cut the C paragraphs, followed by as many of the B paragraphs as needed to reach your length goals.

Make these kinds of cuts, repeating if necessary, until the text is at or just under the target length. Now re-examine and rewrite the section to be sure that it is still coherent, that transitions make sense, and so on. If this rewriting pushes you over the length limit, go back and cut again. When cutting a technical paper, it is tempting to keep all the “real content” and to remove motivation and examples. Resist this temptation.

Exercise L: Writing the abstract Writing a scientific abstract is a specialized art. To practice this art, follow the advice given by Landes (1966): make sure the abstract includes the essential information presented in the paper (Depending on whether you have significant experience reading and analyzing technical papers, your teacher may wish to begin instead with Exercise M.) To prepare for the exercise, the group leader should take a technical paper and remove the abstract. Since this is one of the few exercises for which group members will have to read an entire paper, it helps if the paper is well written, easy, and of interest to most members of the group. The exercise has two parts:

  • To prepare for writing group, read the paper and mark those points that you think constitute the “essential information” that should be presented in the abstract. Highlight, make a list, or do whatever works for you.
  • In group, attempt to prepare abstracts at two of the more common lengths: 200 words and 50 words. As time permits you may also try 300 or 100 words. If you are motivated to write an abstract ahead of time, by all means do so.

If you are pressed for time and cannot read the whole paper, you may do almost as well by abstracting what you find in the introduction and conclusion. Our experience is that an interesting paper usually requires two sessions: In the first session, we agree on what constitutes the essential information in the paper. In the second session, we write abstracts. Because the actual writing requires that we choose suitable subjects and verbs and manage the flow of information well, it helps to do this exercise after you can apply these techniques successfully.

Exercise M: Reading the abstract Finding the essential information in a paper requires real intellectual work, and if you don’t already have practice do- ing this kind of work, it may be that your teacher won’t have time to teach it. A reasonable substitute for Exercise L is to read some abstracts instead. Choose a handful of abstracts. For easy reference, number each sentence of each abstract. The exercise is as follows:

  • For each numbered sentence, say whether the sentence actually presents information or whether it merely promises information.
  • Find the abstract that the group likes best, and the one that the group likes least. Is there any relationship between what the group likes and an abstract’s ratio of promises to presentation?

3.3 Supplementary guidelines

We have developed some useful guidelines that we do not yet know how to turn into crisp principles or exercises.

  • You may well have a nest of interrelated concepts for which there is no ob- vious order of presentation. To come up with an order, you may have to tell lies, i.e., make simplifications for pedagogical purposes. Such simplifica- tions should be announced. For example, you could claim for pedagogical purposes that a variable stands for a number, not a location. Another technique is to mention a concept without defining it. For example, you might say “Let’s assume that l is a location on the stack, without going into the details, which are in Section 12.” Checklist: Is every concept mentioned before it is used? Are most concepts defined before use?
  • Types help. Do you give the type of every operation?
  • Do you explain the name of each variable? Do you explain what each Greek letter may stand for? For example, do you explain that ρ stands for an environment?
  • When presenting abstract data types, we are aware of two styles. Hoare’s style talks about the abstraction represented by a type and explains the concrete operations by their effects on the abstraction. For example, Hoare might explain an environment by using the abstraction of a set of bindings, and he might explain lookup by finding a binding with a given left-hand side. Algebraic or equational style (owing much to Goguen and Guttag) gives equations that relate concrete operations on the type. Equations can usually be turned into a term-rewriting system that can specify results returned by observers. For example, algebraic style might rewrite a lookup operation into the value looked up (by substituting equals for equals at every step). Checklist: Do you know what style you are using? Are your definitions and examples all consistent with that style? Do you wish to use both styles? If so, have you explained the redundancy to your reader?

References

Martha Beck. 2003 (July). Ready... Aim... Oh, well.... Oprah magazine.

This short article suggests ways of overcoming (or working around) one’s perfectionism. It may be useful for writers who have trouble producing.

Howard S. Becker. 1986. One right way. Chapter 3 of Writing for Social Scientists: How to Start and Finish Your Thesis, Book, or Article, Chicago Guides to Writing, Editing, and Publishing. University Of Chicago Press. This chapter debunks a few myths and contains helpful advice about writing practices.

Robert Boice. 2000. Advice for New Faculty Members. Allyn & Bacon.

This book is full of priceless data and practical suggestions about what sorts of behaviors characterize writers who are successful, productive, and take pleasure in their work. Unfortunately, I find much of the material poorly presented or difficult to understand. It nevertheless repays careful reading. (Boice’s older title, Professors as Writers, is well reviewed, but I have not read it.)

Joan Bolker. 1998. Writing your dissertation in fifteen minutes a day: A guide to starting, revising, and finishing your doctoral thesis. Macmillan. Bolker explains many of the same writing behaviors and habits that Boice (2000) does, but in a form specialized for doctoral students. As you might guess from the title, Bolker, like Boice, advocates for brief, daily sessions. If you find Boice difficult to read—full of jargon and written from a strange social-science point of view—then you might want to try Bolker. If you can translate her prescriptions from the doctoral setting to your own setting, or if you happen to be writ- ing your doctoral dissertation right now, you will probably value her recommendations.

Kenneth A Bruffee. 1999. Collaborative Learning: Higher Education, Interde- pendence, and the Authority of Knowledge. Second edition. Johns Hopkins University Press. This book is somewhat controversial for its views of how people learn and what higher education really means, but I have found it invaluable for its suggestions about how to teach discussion classes.

Chicago Editorial Staff. 1993. The Chicago Manual of Style: The Essential Guide for Writers, Editors, and Publishers. University of Chicago Press, fourteenth edition. I find this edition more readable than the fifteenth. The fifteenth edi- tion does have a lot more information about citing electronic sources.