Dave's Writing Guidelines

Over the years I have collected a few thoughts on the preparation of research papers.  So I list them here for easy reference. You might also enjoy my tips for authors of MobiSys papers.

Format:

See Tips for squeezing text out of latex papers.

Structure:

Your paper draft should have a title, authors, date, revision number, and abstract.
A typical structure is

Publishers

I made a list of the publishers that I commonly use, with links to their copyright policies.

Usage:

Here are some things that I commonly find a need to mark on student papers (and my own too!). I mark them by writing the number in a circle, in the margin. I tend to mark only the first one or two occurrences of any given mistake in any given paper. I don't try to explain all of them fully here; see some of the books below for specific advice about English usage. Day's books are particularly good for learning the conventions used in scientific writing.
  1. Check your spelling!  You're writing the paper on a computer, a computer that can check your spelling.  Use the spell checker!  It can catch many typos.
  2. Hyphenate compound words that are used as an adjective.  For example, in "open-book exam", the phrase "open book" is used as an adjective for the noun "exam."  These hyphens are used much like parentheses; "open-book exam" is read like "((open book) exam), whereas "open book exam" is read "(open (book exam))", not the likely meaning.
  3. Be careful how you use "which" and "that".  "Which" nearly always follows a comma, because it is used to add information, whereas "that" is used to qualify:
  4. In the first sentence, there is only one ball involved, and we mention almost as an aside that it is a red ball.  In the second sentence, there are presumably many balls involved, but it is the red ball that fell down the hole.  The following sentence is ungrammatical:
  5. Commas can be tricky. Here is an interesting article about some subtle comma issues.
  6. Avoid the passive sentence structure.  It obscures the subject of the sentence, and leads to ambiguity. See Dupré 1
  7. Do not use contractions in formal writing.
  8. Avoid verbosity:
    1. "In order to..." becomes "To..."
    2. "At this point in time" becomes "At this time"
    3. "a number of" becomes "several"
    4. "utilizes" becomes "uses"
  9. Do not underline words and phrases.  For emphasis, foreign words, etc., use italics.
  10. The abbreviations "i.e.", "e.g.", "etc.", "vs.", are indeed abbreviations and thus should have periods as shown.  Of those, "i.e.", "e.g.", should always be followed by a comma, as should "etc." when in the middle of the sentence.  (Why? because they replace "that is", "for example", and "and so forth", which are always delimited by commas.) At the end of a sentence I prefer to use "and so forth" rather than "etc.."
  11. If you want to mention a URL...
    1. do not place it inline, in the text.  Put it in a footnote, or a reference at the end of the paper.  A footnote is nice because the font is generally smaller, and it starts on a new line, so the URL can generally fit in one line and not mess up the line-wrapping in the text.  Plus, few people actually want to read a URL, though they still might want it handy for reference.
    2. Avoid URLs that refer to CGI scripts, as these tend to have a short lifetime.
    3. If the URL is for a publication (book, article, magazine, news story), give a full traditional citation of the publication itself , but include the URL for the reader's convenience.
  12. Do not end a clause or sentence with a preposition (with, for, to, from, under, on, in, and so forth). See Dupré 60.
  13. "This" should almost always be followed by a noun: instead of saying "this is red", you should be more specific with "this ball is red."  If you leave it out, your reader may mentally insert a different noun than you had in mind... things that are not ambiguous to you can be ambiguous to your reader.
  14. It is rarely useful to use the word "very".  How much hotter than "hot" is "very hot"?  This story may be apocryphal, but Mark Twain once said that he would just replace "very" with "damn" everywhere, and then the editor would surely take them all out.
  15. "However" should (usually) not begin a sentence: rewrite "However, I found that the red ball had been missing for weeks" as "I found, however, that the red ball had been missing for weeks". Then, note that "however" should be surrounded by commas.  It is ok for it to be at the end of a sentence, however. Above, I say "usually" because this is not a hard and fast rule, as suggested by Diana Hacker's Handbook.
  16. It is rarely appropriate to say "whether or not"; usually you should just say "whether".  If you do use "whether or not", don't spread the words across the sentence.  See Dupré 73.
  17. When writing about general interconnected computer networks, call them internets (not capitalized). When writing about the specific public internet that is based on the IP protocol, call it the Internet.  The Internet is an instance of all internets.  Unfortunately it is common, though technically incorrect, to equate the Internet and the World-Wide Web (which is also capitalized, please note).  The WWW is a subset of the Internet.
  18. When referring to your own experimental results, use the past tense.
  19. When referring to other parts of your paper, use present tense.  That is, do not say, "This paper will discuss...", say, "This paper discusses...".  Similarly, say, "The argument above proves that..." rather than "The argument above proved that...".  Why?  Because, despite the fact that your reader is reading through the paper, over time, the paper stands complete, in the present.  The argument not only proved, but still proves....
  20. Place a footnote mark outside the punctuation when at the end of a sentence.  Like this.2  Not like this3.
  21. It is common in scientific research papers to use the first-person plural, that is, to write "We developed a method..." rather than "I developed a method...", even on a single-authored paper. The rationale I've heard is that the plural recognizes that science is normally a collaborative process.
  22. Avoid using a slash when you mean "and" or "or". If you write a slash, the reader may have a different interpretation than you.
  23. Capitalize the word "Figure" when referring to a specific figure, such as "see Figure 4." Same with Section, Table, Equation, etc. Do not abbreviate these words.
  24. A floating figure or table should always appear on the same page, or a later page, than its first reference in the text. LaTeX will arrange this placement properly as long as you put the {figure} or {table} environment after the first \ref to that float. My practice is to put the environment immediately after the end of the paragraph containing the first \ref. The forward-reference is ok and is resolved by the second pass of LaTeX.
  25. Citation references are not nouns; they are parenthetical remarks. Thus, it is not correct to write "In [13] they show that P=NP." You should write "A seminal paper proved P=NP [13]." Or, "Jones and Smith show that P=NP [13]." The reference can go at the end of the sentence (my preference) or at the end of the relevant phrase (sometimes better when multiple refs are cited in the same sentence). Note: plus use a non-breaking space (a "tie") right before the reference, so it won't appear at the start of a new line, like this
    [13]. In LaTeX, use a tilde for a non-breaking space: "blah~\cite{jones:PNP}." See also the note about "et al." below.
  26. Reduce "ink" in tables and graphs. I often see tables with a line all the way around the table, between every column, and between every row... ugh, it looks like a spreadsheet. All that "ink" is unnecessary and distracting. Read Tufte's book (below); it will transform the way you think about presenting data.
  27. Ensure diagrams and graphs are visible when printed on B&W printers - many readers (and reviewers!) still print the papers they read, and many do not routinely use a color printer. Check out this interactive color exploration tool and note the checkboxes for "colorblind friendly" and "print friendly" modes.
  28. Units: The convention in computer science seems to be the following: when measuring storage, mega and kilo refer to powers of two; thus a megabyte is 220 bytes and a kilobyte is 210 bytes. When measuring network bandwidth, mega and kilo refer to powers of ten; thus one megabit-per-second is 106 bits per second, and one kilobit-per-second is 103 bits per second. When abbreviating, k=103 but K=210, and m=106 but M=220. Furthermore, b=bits and B=bytes. Thus, 10 MB is 10 times 220 bytes, but 10 mbps is ten million bits per second.
  29. In LaTeX, when ending a sentence with a capital letter and a period, you need to tell LaTeX that it is the end of a sentence and not an abbreviation in mid-sentence. For example, my name is David F. Kotz. The "F" in that sentence is a capital letter followed by a period, and LaTeX rightly supposes that it is not the end of a sentence. LaTeX puts a little more space between sentences than between words, so it is good to get it right. As another example, I started a project called CRAWDAD. That sentence ends with a capital letter and a period; in LaTeX, it should be coded like this: CRAWDAD\@.
  30. The Latin phrase "et al." is often used to abbreviate a long author list. Note that the first word et is a word and the second al. is an abbreviation, so only the second has a period. Format this phrase in LaTeX as "et~al." The tie (tilde) prevents a line break in the middle, which is awkward. If the phrase appears in the middle of a sentence, format it as "et~al.\  " (where there are two spaces following the backslash). The backslash-space-space tells LaTeX the dot is not an end-of-sentence period and should be followed by an inter-word space rather than an inter-sentence amount of space.
  31. The em-dash is a long horizontal line mdash; like that mdash; used to set off a remark from the rest of the sentence. There are two common approaches to formatting an em-dash — with and without spaces. I prefer to use a non-breaking space prior to the em-dash, and a breaking space after the em-dash. In LaTeX, like this~-- note the tilde, the double dash, and the space. (The other method would be like this---note the triple dash.)

Recommended reading: