Comments on Writing

Richard Hughey

February 17, 2004

This is a list of things I’m tired of correcting — if too many of these are violated, I may return the work unread. The list includes typesetting, grammar, and style, and is not complete.

If you are giving a talk (thesis proposal or defense) provide the text one month before the talk to the readers after it has been okay-ed by your primary advisor. Be sure to send a copy of your abstract to the appropriate staff member at the same time you schedule the talk. Allow at least two weeks or more after your talk to work on changes (this is particularly important for taking part in commencement). Before presenting the proposal or thesis to your committee, ensure that your advisor has completely read the draft and that you have integrated all your advisor’s comments

1 Typesetting

Most people use L^{A}TEX. I personally use the article style with some margin changes (fullpage.sty can be a bit much; you may want to adjust them by hand or, as in this document, use largepage.sty in my tex directory). Various conferences, or individual esthetics, often lead to a desire to make L^{A}TEX to different things. Many other people have found this too, thus there is a vast repository of style files and hacks both on the net and around here. See ~rph/tex/README for a description of all my favorite style and bibliography files, as well as answers to a few frequently asked questions and pointers to archives.

1. L^{A}TEX uses inter-word spacing between words ending in capital letters, such as U. C. Unfortunately, this means that when you end a sentence with a capital letter, you do not get inter-sentence spacing, and must use C\@., as in C. Notice how the spacing is larger than in the first example. Do this for every sentence that ends with a capital letter. Regular expression search and replace will do wonders.

2. Use as few fonts as possible.

3. The hyphen is indicated with a single ASCII dash (as in application-specific array processors), number ranges with two (97–100), and dashes with three — like this. Placing spaces next to the dash is optional, but be consistent. Dashes, as with many other things, should not be overused. Note the use of a hyphen to form a compound adjective, above.

4. Words in mathmode require mboxes. Note the different spacing between Instr count_{i}

     ($V_{Instr\_count}_i$) and Instr count_{i} ($\mbox{\em Instr\_count}_i$ or alterna-

tively {\em Instr\_count}$_i$). The first is ugly.

2 Grammar and other small matters

Here are a few trivial errors that often come up.

1. Be consistent in your use of commas in lists. Choose and consistently use one form, as A, B, and C; or A, B and C. Occasionally, for clarity, in either of these schemes the other is used, but not often.

2. Know the difference between that and which. The first is defining and restrictive, while the second provides extra information that can be eliminated without changing meaning. Clauses using the second, which can appear in any writing, are usually separated out by commas.

3. Proofread your bibliography and ensure all items have dates and page numbers, and that author and journal names are identical if they appear more than once. The bibliography is one of the most fruitful places to look for errors.

4. Spell out small numbers like one and two. When writing numbers less than one, always include a leading zero (0.5, not .5). Do not include an excessive number of insignificant digits. Two or three significant digits often suffices.

5. Do not treat citations as nouns; they are not grammatical elements. For example, “Smith and collegues did something exciting [1],” rather than “[1] discusses exciting work.”

6. Be sure to spell check and proofread. This one often gives me problems.

7. In lists, itemizations, and even paragraphs within a section, use parallel constructions where appropriate — not necessarily the same words, but at least similar structures. A trivial incorrect example would be using “first” followed by “secondly” in a list. This is particularly important when the items are closely tied together. In this document, most items are in imperative without a pronoun. Adding an item starting with “You should” would violate this idea.

3 Style

1. Avoid the use of passive voice, such as “A machine was built to solve the problems of the world.” One alternative is the editorial we, as in “We built a machine that solves the problems of the world.” Editorial we can be as overused as passive voice, however, so try to use it only occasionally, if at all. Instead, write short, snappy, assertive statements such as “Our machine solves the problems of the world!” Passive voice is particularly bad in abstracts — the abstract should draw the reader into the work rather than put the reader to sleep.

2. Include a solid section on related work.

3. If you wrote code, spend some time talking about performance and implementation.

4. Write short sentences and paragraphs and use lots of sectioning commands, especially in dissertations. Topic sentences should be favored as well. Use short words, too!

5. Remember my favorite passage from Strunk and White (an excellent book to review before any major writing project): “Rather, very, little, pretty — these are the leeches that infest the pond of prose, sucking the blood of words.”