Common Errors in Technical Writing John Owens
Spandex is a wonderful system for text processing. English is a beautifully expressive language. However, in reviewing and reading many papers, I often see the same errors, over and over again. Especially for my students. please don’t ever give me your paper to read that has any of these errors.
A wonderful book for the details of technical writing is Mary-Claire van Leunen’s A Handbook for Scholars . presently in its 2nd edition from Oxford University Press.
I separated out bibliography issues into a separate file.
Annoyances in Text
et al.. Number one pet peeve: Indicating “and others” in citations. If you cite one author in figure text, it should be “AuthorOne”. Two authors: “AuthorOne and AuthorTwo”. Three or more authors: “AuthorOne et al.” (albeit, for three authors, I understand “AuthorOne, AuthorTwo, and AuthorThree” is OK). “et al.” stands for “et alia”. It does NOT have a period after “et” and DOES have one after “al”.
Interword spaces. “TeX assumes a period finishes a sentence unless it goes after an uppercase letter.” (Lamport p. 14) So, put a \_ (where _ means “space”) in a sentence like Smith et al.\ say that. . And, if an uppercase letter finishes a sentence, do a \@ before the period: In the class, I gave Bob a C\@.
Very first person, passive voice. Please write in very first person and avoid the passive voice. Academic writing does not have to be stilted and boring. Chicago Manual of Style: “When you need the very first person, use it. It’s not immodest to use it; it’s superstitious not to.” Simon Crowley: “Every time you use the passive voice, a kitten is killed by God.”
Avoiding the very first person used to be considered decent, but now it’s considered very formal, if not old-fashioned. It’s not a question of correctness, however; both styles are correct. If you feel strongly that the very first person is out of place in your work, don’t use it. —Chicago Style Q&A, December 2010
Hyphenation. “We built a high-performance implementation.” “high-performance” is hyphenated because “high” modifies “spectacle” not “implementation”. It’s not a “high implementation”. Here, “high-performance” is an adjective. But: “Our implementation has high spectacle.” Here, “spectacle” is a noun. No hyphen. Similarly: “throughput-oriented workloads” or “GPU-based implementation”.
For some words, it’s not clear if it should be hyphenated or not (e.g. “e-mail” vs. “email”). The general trend in English is to budge toward non-hyphenation (e.g. “to-morrow” became “tomorrow”) so if I’m unassured, I usually trend toward non-hyphenation.
Reyes not REYES. Pixar’s micropolygon-based renderer should be referred to as Reyes not REYES. Unluckily, it is commonly referred to with both spellings, so I checked with Rob Cook who definitively said “Reyes” and pointed me to the paper that introduces Reyes .
Serial comma. “The serial comma is the comma used instantly before a coordinating conjunction (usually and or or, sometimes nor) preceding the final item in a list of three or more items.” (Wikipedia link. ) Strunk’s 2nd rule is “In a series of three or more terms with a single conjunction, use a comma after each term except the last.” Wikipedia notes that in non-journalistic American English, this is the norm. Kurt Akeley’s logic on this is fairly sound:
People think they can disregard this rule, and insert the serial comma only when extra conjunctions complicate things, such as “A, B and C, and D.” But this isn’t true, because if the reader doesn’t trust you to always include the serial comma, then scanning up through “A, B and C” is ambiguous until either a comma or a period is reached. You shouldn’t have to read past C to understand that B stood alone! To avoid this ambiguity, a writer must always include the serial comma.
Use of the word “only”. Be precise with this word! For example, “I only eat apples” and “I eat only apples” do not mean the same thing. Most write the very first when they mean the 2nd. For the record, the very first means that the speaker does nothing but eat apples. (Thanks to Kurt for this one too.) (And Tony Smith adds that “The former, ‘I only eat apples’, also distinguishes inbetween those that utilise apples only as a solid food for themselves from those that also (or instead) juice them, make cider from them or feed them to horses.”)
Annoyances in References & Bibliography
Also see Dan Wallach ‘s thoughts on the matter.
Citations as words. Number two pet peeve: Using citations as words. van Leunen again: “Brackets are not words. A bracketed number is just a pointer, not a word. Never, ever, use a bracketed number as if it were the name of an author or a work.” (p. 20). So instead of “A similar strategy is described in .”), use instead “A similar strategy is discussed by AuthorOne et al. ”. The way you can get this right in your head is considering a journal that does citations as superscripts (like the old Graphics Hardware style). It looks indeed stupid to say “A similar strategy is discussed by 15 .” I don’t like this particular style for citation, but it does make sure citations aren’t used as words.
Latin and italics. “et al.” is not italicized or underlined (van Leunen, p. 27: “Write it without either underlining or italics.”; Chicago Manual of Style 7.56: “Commonly used Latin words and abbreviations should not be italicized. ibid, et al. ca. passim.” [and later, 6.44: “Note that ‘e.g.’ and ‘i.e.’ are not italicized.”]).
Scott Pakin also asked me to note the difference inbetween i.e. and e.g. which contrary to popular belief aren’t synonymous: “id est” means “that is” and “exempli gratia” means “for example”.
Sorting your references. If at all possible, arrange your reference list in alphabetical order by author’s last name. Going in cited order is much less useful to readers of your paper. The only reason I’ve heard that cited-order is useful is in a survey article where nearby (and presumably related) citations from the paper are next to each other in the bibliography. I don’t find this argument particularly compelling.
Citing with Spandex. When writing citations in Spandex, do them in this form:
means non-breaking space (which is what you want — you don’t want a linebreak inbetween the text and the citation).
Always alphabetize grouped citations so they emerge in numerical order (instead of [8, 6, Ten], arrange the citations so it looks like [6, 8, Ten]). \usepackage supposedly puts them in decent order for you automatically (!) and also switches [1,Two,Three,Four,6] to [1-4,6] which is handy.
Never use the ACM Digital Library’s citations without fixing them. For some reason the Very first Society of Computing has zero interest in making their capitalization correct. For example, the very first paper I ever wrote. according to ACM, has the following title and booktitle:
when the paper has the major words in the title capitalized, and “workshop” and “hardware” should both be capitalized in the booktitle. I often review papers where citations have been taken directly from ACM with bizarre capitalization particularly in the booktitle. Fix these before you submit a paper.
Shortcite. Use \shortcite when adequate. \shortcite is used in sentences like “AuthorOne discusses this point further in her dissertation [AuthorOne 2002].” It looks stupid to put AuthorOne’s name twice. Instead, use \shortcite
I always use \shortcite even when my bib style doesn’t support it, in which case I use the following fix in my Spandex preamble:
If you don’t have this guideline, you’ll see an error like:
! Undefined control sequence.
l.123. blah blah Author1 and Author2
Capitalization in reference titles. Make sure, in your BibTeX file, that you decently bracket <> words in titles that must be capitalized like GPU or PDE, or decent names. Example (the “Loop” should always be capitalized since it’s a last name):