Writing Pet Peeves: Correctness, References, and Style

Correctness

• contractions: Avoid contractions in formal technical writing.

• its: Note "it's" is a contraction for "it is", not a possessive.

• citesinvisible: Citations are grammatically invisible, you shouldn't use them for nouns. Correct: "The PivotGraph system [13] features a derived aggregate network". Incorrect: "Aggregation is also used in [13]".

• hyphenation: Whether to hyphenate a noun phrase depends on how it is used. Use "foo bar" when a noun phrase is used as a noun, and "foo-bar" when the phrase is used as an adjective. Correct: "we lay out elements end to end in a line" (noun), "we make an end-to-end argument as in networking" (adjective).

• layout: In a similar spirit, "lay out" is a verb and "layout" is a noun. Correct: "we lay out the graph splendidly" (verb use), "the layout is splendid because" (noun use).

• principal: Please get principal/principle right. The mnemonic is principal = main, principle = idea. PCA stands for Principal Components Analysis. PI stands for Principal Investigator. When you're talking about perception, you're discussing perceptual principles.

• itemscap: When you refer to specific items like figures or sections within the paper, you must capitalize them. Correct: "We show in Figure 1 the chaotic situation described in Section 3.2". Incorrect: "We show in figure 1 the mayhem alluded to in section 3.2".

References and Cross-references

• Always use the LaTeX label/ref mechanism for figure and section crossreferences. Never hardwire them, it's a disaster waiting to happen: inevitably something will get renumbered and it's extremely hard to spot the new bug when proofreading. Include supplemental materials in the same latex project as the main paper, not a separate one, so that you can cross reference between them easily.

• Always use the bibtex/ref mechanism rather than hardwired citations in the main text. As above, it's a gold-plated invitation to disaster.

• If you find a paper on arxiv.org, always check if it's been subsequently published elsewhere: if so, you should hunt down the correct published reference and use that in your bibliography. That information is occasionally visible in the comment line of the arxiv page which you can check first, but then always double-check the title with a google search. The same holds for technical reports from a university or industrial research lab, always check if there's a more recent published version. It's nice to also include the non-paywalled arxiv or TR URL if there's no freely available version of the final thing, but correctly citing the final publication venue is more critical.

• In a bibliography, always always hand-check bibtex that you get off the web. It's usually inconsistent or incomplete.

• Be consistent with journal/conference names. No need for publisher address unless it's someplace obscure, and no need for publisher if it's implicit in the conf/journal name (i.e. IEEE/ACM), and no need for the location of the conference. Always doublecheck that the pages are in there (both the start and end page!). The only acceptable exceptions are when it really is an online-only venue where there are no explicit pages (examples include the BELIV workshop proceedings or the Foundations and Trends in Human-Computer Interaction journal).

• Also be concise and consistent: 'Trans.' not 'Transactions', 'Symp.' not 'Symposium', 'Conf.' not 'Conference'. Don't include words like "of the" or "on". Don't ever say 'pages', just 'p.' (In some cases this style advice from me is overridden by the explicitly stated requirements of a specific venue. Same with point just above.)

• Do include the accepted nickname/shortname for conferences in parentheses after the long name. Don't include the year after that nickname, it's already communicated by the year that comes at the end of the citation.

• Example of bad bibliography snarfed off the web:
  "M. Wattenberg. A note on space-filling visualizations and space-filling curves. In Proc. of the IEEE Symposium on Information Visualization (INFOVIS'05), volume 0, page 24, Los Alamitos, CA, USA, 2005. IEEE Computer Society."

  After fixing:
  "M. Wattenberg. A note on space-filling visualizations and space-filling curves. In Proc. IEEE Symp. Information Visualization (InfoVis), p 181-186, 2005."

• If you're pressed for space, change long author lists to 'FirstAuthor et al'. I normally do full names for four or less, and switch to et al for five or more. The way to do this in latex/bibtex is "John Smith and others" for author list.

• Make sure that you've got the right capitalization in titles and journal names. In latex/bibtex that means using curly braces around elements that should not be lowercased automatically. Main offenders are "D" (3D, ND), acronyms, and camelCase names.

• In short: check your bibliography very carefully. Do not be sloppy and inconsistent. Be assured that I will notice.

• In long: read this eloquent post by Niklas Elmqvist on The Art of Clean References, I vehemently agree with 98% of what he says.

Figures

• compression: When creating screenshot figures, always use uncompressed PNG instead of compressed JPG format to avoid aliasing artifacts.

• subfigcaptions: For captions, use parentheses around the subfigure labels to distinguish them "(a) blah blah". Always have a (possibly short) bit saying what the full figure does before starting with subfigure descriptions. Each subfigure should have its own label, rather than having a continuing sentence where you mention subfigure bits as you go. Correct: "Key aspects of foobar. (a) The first thing. (b) The second thing." Incorrect: "The first thing is great (a), and I love the second thing (b) too".

• figref: Every figure must be referenced in the main body text.

Style

• parens: Avoid parentheses whenever possible, they interrupt flow. It's OK to use them when defining acronyms, but otherwise I try to hold myself to only one parenthetical remark per paper (with some exceptions for irreconcilable differences with a coauthor's preferences).

• latin: Avoid "e.g." and "i.e.", spell out "such as" or "for example" instead. Again, it's a flow issue.

• possessives: Minimize use of possessives with nouns. So instead of "feature's sequences", say "sequences of a feature". It's easier to parse.

• this: Avoid "this" without a noun after it, especially at the beginning of a sentence. Instead of "This shows that we are fabulous", say "This situation shows that we are fabulous", to make the referent unambiguous.

  I quote Ullman's section on "Avoid non-referential this":

  While it sounds pedantic at first, you get a huge increase in clarity by chasing the "nonreferential this" from students' writing. Many students (and others) use "this" to refer to a whole concept rather than a noun. For example: "If you turn the sproggle left, it will jam, and the glorp will not be able to move. This is why we foo the bar." Now the writer of this prose fully understands about sproggles and glorps, so they know whether we foo the bar because glorps do not move, or because the sproggle jammed. It is important for students to put themselves in the place of their readers, who may be a little shaky on how sproggles and glorps work, and need a more carefully written paragraph.
  Source: Jeffrey D. Ullman, Advising students for success, CACM 52(3):34-37, March 2009

• oxfordcomma: Always use the Oxford/serial comma with lists. Instead of "we have apples, oranges and bananas for sale", say "we have apples, oranges, and bananas for sale". The final comma is critical for resolving ambiguity in some situations. Like these:
  • Merle Haggard and the Gay Serial Comma
  • Strippers, JFK, and Stalin Illustrate Why You Should Use the Serial Comma

• passive: Avoid the passive voice, use active voice. Passive voice makes your text too ambiguous about who is the agent of action. It's especially a problem in technical writing because it can obfuscate the contributions: did the authors do something, or was it done by somebody else? Clarity is crucial here!

• subsec: You must have some prose between section and subsection header. (Sadly enough, when you're cutting for length!)

• justdoit: Avoid "in this section we do XXX". Just *do* XXX! (I sometimes violate this rule myself, but it's an aspiration...)

• firstdef: Emphasize a word (with bold or italics, as you prefer) when you first *define* it, not when you first *use* it. Ideally the definition and the first use are the same, but it might be a sentence or two later.

• no-lys: Firstly vs. first is admittedly an issue of personal preference. I strongly prefer the latter. Let me bring your attention to a quote from Elements of Style: "Do not dress words up by adding 'ly' to them, as though putting a hat on a horse."

• doublenegs: Avoid double negatives, use a positive instead because it's easier to parse.

• parallelstruct: Use parallel structure when possible, both at the level of sentences in a paragraph and at the level of section naming. Correct: Naming Foo, Linking Bar, Adding Bat. Incorrect: Name Foo, Linking Bar, Bat Additions.

• tenses: Avoid switching between tenses unless you have a very good reason to do so. Usually what you're reporting on in the paper should stay in the present tense (Correct: "the system is designed to do foo". Incorrect: "the system was designed to do foo".) Past tense should be reserved for things truly in the past, like what users did during a user study.

• allcaps: Never use all-capitals text in the main body of a piece of writing, and I recommend avoiding it even for slide titles. It's harder to read because of the lack of shape contrast in the letterforms. See https://practicaltypography.com/all-caps.html.

• owens: Plus everything that John Owens says here: http://www.ece.ucdavis.edu/~jowens/commonerrors.html

• dupre: Plus everything in the splendid grammar book Bugs in Writing by Lyn Dupre