This appendix is a mish-mash of things we want to say to students, but that we have not found a natural home for elsewhere in the workbook. Most of the comments are a result of things we have seen done poorly by previous years' students. We recommend reading this appendix at the beginning of the quarter.
We have divided things roughly into 6 sections: content, discourse structure, format, sentence structure, punctuation, and word choice. This order is almost the same as the order you use in writing the paper. Content should be the first thing you consider; formatting should be part of the final polishing. No single section should be regarded as more important than the others, although we may choose to concentrate on different aspects of your writing in different assignments.
In most technical writing, the content is the most important aspect of the document. Be sure your information is accurate and complete.
What we look for in the content will vary with each assignment. We try to anticipate what things people will leave out, and what extraneous material will be included, and warn you about them ahead of time, but writers are ingenious at finding ways to fool us, and errors that we did not expect crop up all the time. The new content errors will be discussed in class after each assignment.
This section covers stylistic problems that are above the sentence level. There are four areas that commonly cause problems: sections, paragraphs, pronouns, and tone.
Technical writing is often consulted, rather than read from beginning to end. You must use clear informative headers for your sections, so the reader can find the desired information quickly. If the sections are too long, the reader won't have enough headers to find info quickly. If the sections are too short, the headers won't stand out enough from the body of the text. Don't look for solid rules about how big a section should be--it depends on both the material and the audience.
Your paragraphs should have a single topic, explained in a topic sentence. Your readers will expect sentences within a paragraph to be more closely related than sentences in different paragraphs, so you shouldn't just chop your writing up into arbitrary pieces.
Within a paragraph, the transitions between sentences generally relate the end of one sentence to the beginning of the next. Repeating a sentence subject in adjacent sentences often makes your writing sound choppy and unpolished.
Between paragraphs, the transitions are a little more distant, but the first sentences usually has some reference to the topic of the preceding paragraph. The next paragraph of this explanation doesn't follow that guideline--the paragraphs correspond to different parts of the evaluation sheet, and so I have split this section into subsections.
When you use a pronoun (such as, it, this, these, those), be sure it has a clear antecedent. Pronouns without antecedents are often grammatically correct, but stylistically awful (for example, this sentence could have been It is often the case that pronouns without antecedents are grammatically correct, ... ). Pronouns at the beginnings of sentences are particularly prone to this sort of vagueness.
Students often use pronouns when they would do better to repeat part of the noun phrase. For example, I'd rather see a noun phrase like this message, than the simple pronoun this.
The correct use of this is often tricky. The referent has to be crystal-clear to the reader before you can use this (or those). If another noun phrase intrudes between the referent and the noun phrase you are attaching the article to, you probably can't use this. Many writers use this as a pronoun, particularly in constructions like ``This is due to the fact that ... .'' Although grammatically correct, this usage is poor style. You'll have much clearer sentences if you use this only as an adjective, not as a pronoun. Any sentence that contains ``this is'' or ``it is'' can probably be reconstructed to read more clearly.
Some people err in the other direction, and use incredible contortions to avoid pronouns, particularly I or we. You'd do better to say, I believe the method will work well, than to say It is believed that ... . Don't say we unless there are multiple authors, or you are addressing the reader and mean you and me together. You should only use you for addressing the reader, not some imaginary third-person. The idiomatic usage you can, meaning that someone can, should not be used unless you really mean that the reader can.
Cleaning up the pronouns is something to do in a late draft, but make sure you do it before the final draft.
Technical writing is usually fairly formal. Slang is avoided, people are referred to by their full names (or by their titles and last names), and standard grammar is used. Americans are often too informal in their writing--remember, you don't know exactly who will read what you write.
Part of the formality is expressed by avoiding contractions. Expand don't to do not, can't to can not, won't to will not, and so forth. If you look at this sentence and at the previous paragraph, you'll see that I've used contractions freely--this use of contractions is a deliberate attempt to reduce the formality of the document and make it somewhat friendlier. Formality is not an end in itself--try to judge the right level for the audience and material to be presented.
Trying to avoid the problem of being too slangy, some people try writing in a stiff, formal style. Unfortunately, the result sounds more like a Victorian gothic novelist than a modern engineer. Your aim should be to write crisply and clearly, not stiffly. If you concentrate on presenting the right material to the right audience, the tone should come almost automatically.
Another aspect of tone, confidence, is discussed in Section 3.4.1.
We want all assignments turned in on standard 8 
'' by 11'' paper,
with reasonable margins on all four sides.
The paper should be typed (double-spaced) on standard typing paper,
and should be free of typing errors (``typos'') and spelling errors.
Watch out for doubled words (the same word twice in a row),
particularly from the end of one line to the beginning of the next.
For in-class assignments, we can't expect typing, but we still expect
neatness.
Try to have some clean paper without ragged edges for each class.
Each assignment will have some required standard format (letter, memo, manual, or some such). Most of the standard formats require titles, and many need section headers as well. When you use them, make sure that the section headers are formatted properly, with a blank line before and after each header.
Choosing good titles and section headers is an art--they should contain as much information in as few words as possible. We don't want to see any generic titles this quarter--any one who turns in a final project titled Final Project has clearly not learned much in this class.
When you receive help from a person, you should acknowledge that help, usually in a separate Acknowledgements section, sometimes in a cover memo. When you obtain information from a book, journal, or other printed source, it should be properly cited and included in a References section. In computer science and computer engineering, footnotes are used sparingly, and only for comments that need to be said but are not part of the main flow of the discussion. Do not use footnotes for citations; use a reference section at the end instead. The preferred citation format if none is specified is to put the author's name and the date of publication in square brackets, but some journals specify other, older forms. See [van78] for a more detailed discussion of citations.
Using someone else's work without giving proper credit is plagiarism--the most serious of academic sins. Collaboration and cooperation are fine--this is not a competitive class, but you must always give credit where it is due.
Remember to put you name and the date on every assignment. Most formats have a standard place for the author's name, a title, and the date. For this class, we always want to see your first draft with your partner's comments.
This section covers both stylistic faults and grammatical faults. Correcting stylistic faults will improve your writing; correcting grammatical faults is essential.
The most common stylistic sentence structure faults are run-on sentences. A run-on sentence strings several independent sentences together, often with grammatically correct transitions. Modern style in technical writing favors fairly short straight-forward sentences, with occasional longer ones for variety. Any extremely long sentences should be broken into smaller pieces. But be careful not to go to extremes--a choppy style with all short sentences is as bad having run-on sentences.
Novice writers tend to over-use the passive voice in formal writing. Check each passive sentence to see if it can be made active. Sometimes, however, passive sentences are the best way to say things. For example, the active sentence The student's advisor must approve the choice of courses, is subtly incorrect. It asserts that the advisor has no choice--s/he must approve the choice, no matter how bad it is. The passive sentence The student's choice of courses must be approved by the advisor, is less emphatic about the obligation on the advisor. Perhaps even better is The student must have the choice of courses approved by his or her advisor, which avoids the passive and leaves the obligation clearly on the student, and not the advisor.
Passive sentences can also be used to maintain the normal topical flow of a sentence (from old information to new information). Note how the flow encouraged me to make the previous sentence passive, and how I avoided the passive in this sentence. See [HO91, Chapter 25] for more information on using information ordering in constructing sentences.
Starting each sentence in a paragraph the same way sounds childish. Starting each sentence the same way can sometimes be used effectively in poetry or songs. But starting each sentence the same in technical writing is not a good idea. (If this paragraph does not make it clear how bad the repeated sentence opening sounds, I don't know what will.) Don't vary the sentence starts randomly; try to make smooth transitions from the end of the previous sentence instead.
Repeated starts are not the only bad sentence beginnings. Watch out particularly for There are, There is, It is, This, These, and other contentless beginnings.
Watch out for elided words. For example, the sentence structure If A, then B is often spoken or written as If A, B. The elision of then is grammatically acceptable, but can lead to confusion, particularly if A or B is a list. Compare If a, b, or c, d and If a, b, c, or d with If a, b, or c, then d and If a, then b, c, or d.
The grammatical faults are more serious than the stylistic ones. You can often get away with bad style, but your readers will be seriously confused or offended by bad grammar. For example, always use complete sentences, not fragments. Fragments are acceptable in some literary styles, but not in technical writing. Section 8.4 has some examples of fragments, illustrating how difficult they can be to read.
If you start a sentence with a modifying phrase, be sure it is supposed to modify the subject. A dangling modifier can be unintentionally humorous. For example, Never having passed an exam, the teacher failed the student, says that the teacher flunked the exams, not the student. Similarly, After typing a return, the cursor moves to the next line. asserts that the cursor types.
These dangling modifiers seem to occur most often in the assignment about naive-user documentation, where they are the most dangerous. The less familiarity one has with a subject, the harder it is to figure out what the dangling modifiers are really modifying.
Even if the subject of your sentence is correct, you can confuse your reader if it doesn't agree with the verb that follows. Number agreement is particularly important. Remember that a subject like each of the elements is singular, but subjects like all of the elements are plural. Semantic agreement is also important. The most common semantic problems come from leaving out or mis-placing the actor of an action verb. For example, The data decided me to ... , is wrong--though you could say The data convinced me to ... .
The subject is used as the topic in English. Having a separate topic phrase (As for the procedure, it sorts numbers.) sounds like a bad translation of good Japanese. Rearrange the sentence to make the object of the topic preposition the subject or object of the sentence (The procedure sorts numbers.).
Many non-native speakers have trouble with English tenses. They do not match the tenses of Asian languages in any simple way. If you have trouble with English tenses, see an English-as-a-second-language tutor. Huckin and Olsen's explanation of English tenses is also valuable [HO91, Chapter 31]. Occasionally a native speaker will use one of the more complex tenses (particularly the subjunctive mood) incorrectly. Any standard grammar text should explain the formally correct usage sufficiently for most native speakers.
-) for a hyphen or en-dash, two
(--) for an em-dash.
Spaces should not be used around hyphens or dashes of either sort.
See also Section 3.5.3 for details on hyphens and dashes.
A hyphen is used to join compound words together (for example, mother-in-law), particularly when a complex noun phrase is being used as a modifier. (Be warned: the complex-noun-phrase-modifier style of writing is hard to read.) Hyphens are sometimes used to attach prefixes and suffixes to words, particularly when the word is likely to be misread without the hyphen (for example, pseudo-operation, re-enter, and pre-enroll).
Some students detach prefixes and try to use them as adjectives. The prefixes sub-, pre-, pseudo-, and proto- must be part of another word, either as a single word ( subroutine) or attached with hyphens (Proto-Indo-European).
Hyphens are also used at the end of a line to indicate that a word continues on the next line. Unlike many other languages, English has strong rules about where a word can be hyphenated. You can only break between syllables, and you should have at least three letters before and after the hyphen. If you are not certain, it's far better not to hyphenate than to hyphenate incorrectly. Most word processors that hyphenate do an awful job of it--don't trust them!
En-dashes and em-dashes are different lengths and have different uses. The shorter en-dash is used to indicate a range of values or times (for example, June 30-July 31); the longer em-dash is used to indicate a long pause and a discontinuity in the flow of ideas. If you have too many em-dashes, your readers will think that you couldn't keep your attention on the subject, or that you are hopelessly badly organized.
Quotation marks (``quotes'') are used to enclose a directly quoted statement from another source, or, sometimes, to set off a slang word or deliberately mis-used word. The second usage probably derives from the first, attributing the word to an outside source. Don't use quotation marks for emphasis--use italics or underlines instead. Single-quotes are used for quotations inside quotations. Some fonts have separate left and right quotes (``like this'' and `this'); if yours does, use them. Brackets [ ] are for comments from the quoting author inside a quoted passage. One popular bracketed comment is [sic], which is used to indicate that the error in a quotation was in the original, and was not added in transcription.
We disagree with many punctuation experts on one point--they insist on putting commas inside quotes. This is correct when quoting human conversation or human-to-human writing, but when quoting any communication with a computer, retain the original punctuation inside the quote marks. For example, you type ``mail'', not ``mail.'' Exact punctuation is often critical in computer communications--resist the attempts of those who know no better to ``correct'' your usage!
Parentheses should only be used for additional material that can be omitted without changing the meaning. They are used for short examples, or for comments from the author. Longer digressions usually belong in footnotes, or, better yet, in some other section of the writing. Parentheses bind tightly to the words inside them--there should be no space after a left-parenthesis or before a right-parenthesis (like this). There should be a space before left-parenthesis, and either space or punctuation after the right-parenthesis. If you put an entire sentence in parentheses, the sentence ending punctuation should be inside the parentheses and the the whole parenthetical structure should not be inside another sentence. (That is, you can punctuate such a remark this way.) I, along with many people who compose at the keyboard, over-use parentheses. You can often replace them with commas, or remove the parenthetical comment.
Don't use brackets [ ] in place of parentheses ( ). They serve different functions in English. Although some authors use parentheses for citations, brackets are preferred in most computer science publications. Another use for brackets is to interpolate editorial comments into the middle of a quotation (vulgarly known as butting-in).
Most problems in English punctuation come in the use of commas, which have fairly complex rules. Traditional grammar books and secretary's handbooks (such as Hacker [Hac89]) cover the rules in some detail. One mis-use of commas that is not always well covered is the comma-splice. A splice happens when two independent clauses get joined with only a comma for glue. The problem can be fixed in several ways: by adding a conjunction (usually but or and), by splitting into two separate sentences, or by replacing the comma with a longer pause (usually a semi-colon or dash).
Semi-colons and colons have specific uses. They are not all-purpose substitutes for commas. Huckin and Olsen's explanation seems inadequate, but O'hare's is not bad [O'H86, 142-147].
Watch out for punctuation around Latin abbreviations! The periods that are part of the abbreviation are not used for sentence and clause punctuation (except that an abbreviation at the end of a declarative sentence does not need a double period). The abbreviations i.e. and e.g. should almost always have a comma after them (i.e., like this). You are probably better often avoiding Latin abbreviations.
Put two spaces after a sentence-ending period. Readers rely on that cue to break your text into sentences, and your text can look quite dense and forbidding if you omit the extra space.
This section deals with grammatical and stylistic problems with diction. Many American writers suffer from puffy, pompous writing, particularly when they are trying to write formally. Cut out the words that carry no meaning, watch out for fashionable words and phrases, and, always, know what your words mean! All jargon and acronyms should be explained at the level your audience requires. Generally, more explanation is needed than most authors are aware of. If you're not certain, it's generally better to explain too much than to explain too little.
Certain words and phrases are so commonly mis-used that it is worth looking for them specifically. For example, the -ize suffix can be added to almost any noun or adjective in English to make it a verb, but the result is almost always hideous. (See [SJW79, 50-51].) Utilize, prioritize, and finalize are prohibited--you can use use, rank, and finish instead.
The which/that distinction is disappearing from spoken English (in America), but is still important in writing. Strunk and White [SJW79, 59] have an explanation of the correct usage.
Some words can't be intensified. You can't have something that is ``more unique'' or ``most unique,'' because uniqueness is a property that is either present or absent, nothing in between. Similarly, nothing can be ``especially essential''-- to say A is essential to B means that A is the essence of B, that is, that A is what makes B what it is. Either A is essential, or it is not, but A can be more or less important to B.
Another word that is often mis-used is optimal. When you say that something is optimal, you mean that it is the best--not just good. It is impossible for something to be more optimal, just as it is impossible for something to be more perfect--both should be expressed as more nearly optimal or more nearly perfect.
The expression locally optimal is often used in describing solutions to combinatorial optimization problems, but is meaningless without more information. Technically, a solution is locally optimal if no other solution in some neighborhood is better. Although neighborhoods are usually well-defined in Euclidean space, there are many different neighborhood definitions possible in the search spaces of combinatorial optimization problems. Something can be locally optimal with respect to one set of neighborhoods, but not with respect to a different set.
Speakers of Californian English are fond of adding adverbs to their sentences to slow them down. Most of you are aware that totally is not used as a general intensifier in formal English, but only with the meaning in total. Unfortunately, far too many students use basically and actually as substitutes. These also have exact meanings--look at the corresponding prepositional phrases, which have not been as badly corrupted: as a basis and in actuality. If these phrases don't fit, you are probably mis-using the adverbs--try omitting them.
Non-native speakers occasionally use the wrong preposition. Many preposition usages are idiomatic, and cannot be predicted from the meaning. The only thing to do is to learn verbs and prepositions together. Reading well-written English is the best way to learn the correct combinations. Huckin and Olsen's chapter on informal conversational expressions is also useful [HO91, Chapter 37].
The words first, second, third, ... , last are already adverbs. The constructions firstly, secondly, and so forth are not words.
The word thus is not a shorter form of therefore--it means in this manner, not because of these things. Because thus is already an adverb, there is no word thusly.
One problem that many of us share involves the word only. Because only can modify several different things in a single sentence, it is important to put it in the right place. Unfortunately, most of use tend to move it forward in the sentence so that it modifies the top-level verb. Notice the difference between I'm only working on my homework for an hour, I'm working on my only homework for an hour, and I'm working on my homework for only an hour.
Another strange usage I've seen, but do not understand the origins of, is ``A leaf node is when ...'' for ``A leaf node is a node that ...''.
Recursion comes from the verb recur. There is no verb recurse.
Non-native speakers, particularly Asians, have difficulty using English articles and using singular and plural nouns correctly. Correct usage depends on the noun and on the thing it refers to (its referent). Chapters 29 and 30 of Huckin and Olsen [HO91] have some excellent heuristics for choosing articles correctly.
The most useful heuristic is determining whether a noun phrase has a unique referent, which is occasionally tricky. One case is obvious--when you have already explicitly mentioned the referent. For example, I can now talk about this case, but I can't say ``a case'' or ``one case'' to refer to it. If I haven't explicitly mentioned the referent before, but it is clearly unique (for example, the sun and the moon), I still have to use the, not a. I can't say, ``A first proof was found by ... ,'' because by identifying the unique first proof, I have ensured a unique referent. I can say ``a possible first attempt'', implying that it is not only one possible one. A plural noun can have a unique referent if the set it refers to is unique (for example, the stars or the moons of Jupiter).
You may have noticed that I left that out of the discussion on articles and demonstrative adjectives. It is mainly for pointing to particular objects, usually in contrast to this. For example, ``I want you to use this article, not that one.'' You can probably do fine technical writing for years without using that as an article.