Write It Right
Several Matters of Mechanics
by Judy Goldsmith and Robert H. Sloan
Insert Your Citations in a Graceful Manner
Earlier we discussed when you need to cite, and what you need to gather in your bibliography. The precise format of your citation itself will often be dictated by the journal or conference for which you are writing. There are two common styles: short citation tags that are strings with no white space, often numbers, sometimes names, enclosed in square brackets; and citations that include at least one author's name and a year, and a space between them, typically enclosed in parentheses. The second family of styles are often called APA-like, because they are similar to the style of the American Psychological Association.
If you are using the first style, then your text should scan perfectly without the citation tags. Thus, do not write, "[17] proved that hair color affects programmer productivity." Instead, either name the author(s), using "et al." if there are more than two, or simply state the fact with the cite tag at the end of the sentence. Thus, one can write either, "Hair color affects programmer productivity [17]", or "Smith demonstrated that hair color affects programmer productivity [17]. Subsequently Jones et al. found that punked-out grass green was the most productive color [9]."
Some writers make an exception to the rule that tags cannot be used as nouns for parenthetical remarks intended only to give citations, as in, "(See, e.g., [17,23].)"
Using APA-like citations, you can use the citation either as part of your sentence or as something to be ignored, depending on whether the author name is inside or outside the parentheses for the citation. Thus, in this style, one could write either "Hair color affects programmer productivity (Smith, 2006)" or "Smith (2006) demonstrated that hair color affects programmer productivity."
Obviously Do Not Use Obviously
The word "obviously" and its cognates have no place in technical writing. They are often flags that the writer cannot explain why something is so. This is often because something is not, in fact, so. Furthermore, telling the reader that something is obvious is condescending to those to whom that thing is not obvious.
There is an urban legend about a student who visited the hallowed halls of "insert your favorite snooty institution here". This student did not understand the unspoken rule to never question greatness, so when a math professor said, "This is obvious," the student asked why.
The professor spent the rest of the lecture alternately scribbling on the blackboard and erasing his scribblings. Eventually, the students filed silently out.
For the next week, lights were seen in the professor's office late into the night, and bags of crumpled paper were set outside the office door each morning. The students assembled, waited, and went away.
Finally, class reconvened and the professor came in. He began his lecture at a point shortly before he had been interrupted. When he reached that point, he turned to the class, said, "It is obvious," and continued.
The cognates of "obvious" include "trivial" and the adverb forms "obviously" and "clearly." However, it is reasonable, when you, the author, have done a calculation in full detail and decided that it does not require any deep knowledge of mathematics nor any surprising or clever ideas, to say that a calculation is "straightforward." You may also say that x "follows directly" from y.
Writing style
We encourage you to write in the first and second person, as we have done in this article. Whenever possible, use the active voice rather than the passive voice.
Incidentally, both of those points are part of the IEEE Computer Society style.
Selected Fine Points
This section reflects some of the authors' pet peeves, acquired from many years of writing and from reading and reviewing our students' and colleagues' writing. It is not meant to be a comprehensive list.
Symbols
Symbols are not words, but equations may be part of a sentence When possible, do not begin sentences with symbols. (For further discussion of this, see Knuth (1989).)
When an equation is part of a sentence, then it must be punctuated. For instance, consider
n if n(n + 1),
i =
2.
Note that, as the last part of a sentence, it has a period. If you do not want to punctuate your equations, then do not embed them into sentences.
Nonbreaking spaces
Use nonbreaking spaces where appropriate. Using modern typesetting, you do not decide where your lines of text will be broken by using carriage returns (Chicago, 2003). Your typesetting program makes this decision, and almost certainly will make it differently as you edit your text.
Use a nonbreaking space to tell your typesetting program where it should never break the line even though there is a space. For instance, it is really awkward to have a line break between the word "Section" and the numeral indicating the particular section in the roadmap section of your paper (or elsewhere). In general, you should suppress line breaks between any capitalized name of a unit and the number, for example, "Theorem 1," "Figure 2," and "Equation 3" should all be typeset with a nonbreaking space. Also, when using the numbers in square brackets style of references, many authors like to use nonbreaking spaces to prevent a line from starting with such a reference.
A nonbreaking space is indicated by a tilde character in LaTeX and inserted by
control-shift-spacebar in Microsoft Word.
Hyphen or Dash
Choose the correct hyphen or dash. There are three standard hyphens/dashes in classic typesetting: the hyphen, the en dash, and the em dash, distinguished by length. The hyphen is the shortest, and it is used to join words into compounds, such as anal-retentive. Note that noun phrases are usually not hyphenated, except when used as adjectives. (Of course, anal-retentive students will may already have learned this rule in a high school writing class.)
The en dash, indicated in LaTeX as two hyphens, is used for numerical ranges, such as "pages 9–17".
The em dash, indicated in LaTeX as three hyphens and in Word as two hyphens, is used to splice in sentence fragments.
No space should be left on either side of either the en or the em dash.
Capitalization
Capitalize Algorithm, Theorem, etc. In the bad old days of manual typesetting, capitalization was used for emphasis. Now that we have a plethora of fonts available, including italics and boldfaced ones, this is no longer needed. Capitalization is used for proper names, such as "Madeleine Mayberry3", or "Theorem 5", or for titles, such as "Her Royal Highness", or "Section 7". Thus, one can either refer to "the previous algorithm," or to "Algorithm 12."
In the case where capitalization of phrases is used, it is important to be consistent. If you are capitalizing all the words, then capitalize all the words, except pronouns and prepositions. Pronouns and prepositions do not need to be capitalized in such phrases, except when they begin a sentence. When words are hyphenated together, it is optional to capitalize the word after the hyphen. However, for your prose to look professional, you must choose one option and stick to it for the entire paper.
Apostrophes and "It's" versus "Its"
The apostrophe is used in English to denote contractions, the possessive form of nouns, and to allow an English "s" to be added to a non-English word or symbol. A contraction is the condensation of two words, such as "you are," to one, in this case, "you're." If you want to write of more than one j'accuse, you might write "j'accuse's." Or, you might rethink this desire.
Notice that possessive pronouns such as "his" and "hers" do not have apostrophes. Neither does the possessive pronoun "its." The apostrophe separates "it" from "s" only when "it's" is a contraction of "it is."
Younger readers may be interested to know that the term "carriage return" in the ASCII character set comes from the practice of returning the carriage of an ancient device called a "typewriter" to the left-most column to be written in with a mechanical action that also advanced the vertical spacing by one line.
For punctuation and grammar lessons embedded in deep whimsy and illustrated with wonderful proper names and titles, we recommend the work of Karen Elizabeth Gordon (1993); we also recommend the short classic work by Strunk and White (1999).
Articles (a, an, the) in English
Many computer scientists did not grow up speaking or writing grammatically correct American or British English—or, in many cases, any other version of English. For many of us, the correct use of prepositions and articles is challenging. If you are such a writer, then we implore you to have a native speaker of English proofread your work before you submit it.
Meanwhile, we offer the following two rules:
- If you are discussing a particular or unique object, use "the", and otherwise, if an article is needed, use "a" or "an."
- The article "an" is used only if the following word begins with a vowel (a, e, i, o, u) or a vowel-like consonant (y or h) making a vowel-like sound. For example, "It would be an honor to meet an architect who could build a house on a hill in an hour." The notion of "vowel-like consonants" is not universal.
Introducing acronyms
Always introduce acronyms by spelling out the phrase the first time it is used, followed immediately by the acronym in parentheses. If you want to refer to a MESS, you must first introduce it, as in, Markov indEcision proceSS (MESS) (Chicago, 2003). You should redefine it in each new section in which it is used.
If your acronym is something absolutely standard to your field, you might be able to get away with not introducing it at all. However, you should ask yourself, will others from outside my field read this? Will this acronym still be standard in 10 or 20 years? If so, then you can get away with only spelling it out once.
Scholar's Latin: i.e., e.g., et al., and NB
The abbreviation "i.e." stands for the Latin id est, literally, "that is." Since it is not part of the sentence fragment that follows, it is followed immediately by a comma. It may be used as the beginning of a parenthetical remark. If it is used without parentheses, it should be preceded by a comma.
The abbreviation "e.g." stands for the Latin exempli gratia and means literally, "for the sake of example," and is used in place of "for example." It is also followed, and if appropriate, preceded, by a comma. Both "i.e." and "e.g." must always be written with two periods. Dupr´e (1998) suggests limiting the use of both terms to inside of parentheses, and writing out either "that is" or "for example" for regular text outside of parentheses.
The abbreviation "et al." is short for the Latin et alia, meaning "and others." It is used to cut down a long list of authors in the text, but not in the actual bibliographic information. Some argue that, as a foreign phrase, it should be italicized. Others disagree. All agree, however, that "et" is a full (Latin) word and so it does not get a period, whereas "al." is an abbreviation and so is followed by a period.
"NB" is short for the Latin nota bene, meaning, "note well," and some academic writers use it instead of the English "note that." Some style manuals suggest typesetting it as "NB"; some style manuals suggest typesetting it as "n.b."; some style manuals suggest avoiding it.
Next Column
The next column will discuss the considerations for experimental work.
References
ACM policy and procedures on plagiarism, October 2005.
Bovik, H. Q.; Goldsmith, J. Q.; Klapper, A. Q.; and M. Q. Littman. (April 2003) "Markov indecision processes: A formal model of decisionmaking under extreme confusion", Journal of Machine Learning Gossip, pages 1-9.
The Chicago Manual of Style. (2003) University of Chicago Press, 15th edition.
Dupr´e, L. (1998) BUGS in Writing, A Guide to Debugging Your Prose. Addison Wesley Professional.
Gibaldi, J. (2003) MLA Handbook for Writers of Research Papers. MLA Book Publications, 6th edition.
Gordon, K. E. (1993) The Deluxe Transitive Vampire: A Handbook of Grammar for the Innocent, the Eager and the Doomed. Pantheon.
Gordon, K. E. (2003) The New Well Tempered Sentence: A Punctuation Handbook for the Innocent, the Eager, and the Doomed. Mariner Books.
Handbook of Writing for the Mathematical Sciences. (1998) SIAM, second edition.
Johnson, J. (July 2005) On mathematical writing. Accessed on October 18, 2006.
Kitchenham, B.; Pfleeger, S. L.; Pickard, L.; Jones, P., Hoaglin, D.; Emam, K. E.; & Rosenberg, J. (2002) "Preliminary guidelines for empirical research in software engineering", IEEE Trans. Software Eng., 28(8):721-734.
Knuth, D. E.; Larrabee, T. L.; & Roberts, P. M. (1989) Mathematical Writing. Mathematical Association of America. Reprint (with corrections) of Technical Report 1193, Stanford University Computer Science Department, 1988.
Parberry, I. (1994) "A guide for new referees in theoretical computer science". Information and Computation, 112(1):96-116.
Shaw, M. (2003) Writing good software engineering research papers: Minitutorial. In Proc. 25th Int'l Conf. Software Eng. (ICSE 2003), pages 726-736.
Stone, H. S. (December 1992) "Copyrights and author responsibilities". IEEE Computer, pages 46-51.
Strunk, W. & White, E. B. (1999) The Elements of Style. Longman, 4th edition. The original 1918 edition of Strunk is available online at URL http://www.bartleby.com/141/.
Thomson Scientific. Science citation index. http://scientific.thomson.com/products/sci/
Voice of America. (23 August 2006) "Ohio University accuses engineering graduates of plagiarism". VOA News, August 2006. Downloaded October 11, 2006 from URL
http://www.voanews.com/specialenglish/archive/2006-08/2006-08-23-voa4.cfm.
Zobel, J. (2004) Writing for Computer Science. Springer, 2nd edition.
Judy Goldsmith is a computer science professor at the University of Kentucky. Her research interests include decision making under uncertainty; automation of information elicitation; preference elicitation, representation, and aggregation; computational learning theory, and structural complexity.
Robert H. Sloan is a professor (and acting department head) of computer science at the University of Illinois, Chicago. His research interests include application of computer science theory and algorithms to problems from artificial intelligence, especially machine learning ("computational learning theory") and knowledge representation;computer security, especially access control; and computer science education.