UNIVERSITY OF WISCONSIN-MADISON Computer Sciences Department CS 736/739 Barton Miller

## Writing Suggestions

Below are some guidelines for writing papers for this class.
• Abstracts: The abstract is a complete summary of the paper. It should summarize the problem, approaches and solutions, major results, and conclusions. Abstracts often appear in separate publications, so must stand completely on their own. Avoid phrases that start like "This paper describes..."

• Avoid platitudes: Do not start your abstract, introductory section, or other sections with grand generalizations and fluff. You should start by motivating the problem in a way that carefully delineates the problem that you will solve.

• Etc.: Avoid using phrases such as "etc." and "and so on". If you were going to write "We tested the read, write, fork, etc. system calls.", instead write something like "Some of the systems that we tested included read, write, and fork."

• Label tables and graphs: Here are some guidelines for tables and graphs:
1. All units should be labeled clearly. They can be labeled in the heading to a table column, next the legend for a line on a graph, or in the text below the table or graph.
2. Logarithmic scales can helpful in a graph when there is a wide range of data and there are interesting characteristics in the data for both the small value and large values. They are also useful when plotting an intrinsically exponential behavior. However, most of the time log scales just make the data hard to understand and obscure the magnitude of the relationships between data values. If log scales are to be used sparingly, then log-log graphs are to be avoided even more so.
3. Line up the decimal points in a table column. If the column contains whole numbers, line up the implied decimal point (i.e., right justify the numbers). Never center a column of numbers.
4. Be consistent about the number of decimal places that you present. Make sure that the number makes sense; do not present more precision than is warranted.
5. If you refer to particular table, figure, or section, that reference is considered to be a proper noun, and proper nouns must be capitalized. For example, you would say:
The results in Figure 1 show how intelligence relates to shoe size.
or
The results from the trained-monkey experiments appear in Section 4.1.

• Contractions: Don't use contractions. They are informal and more properly used in spoken speech.

• Quotes: Use quotes to quote another source, such as book or person; do not use quotes to appeal to some fuzzy meaning of a word. For example, avoid uses such as in this sentence:
The technique that we used was "optimal".

• That/Which:: Understand and properly use "that" and "which". "That" introduces a dependent clause (generally, where there is no comma), and "which" introduces an independent clause.

• Passive voice: Use of the passive voice should be avoided. Or, I should say, avoid using the passive voice. Passive voice is less direct and can dilute the impact of your prose. Use it sparingly to create interesting contrast in a paragraph.

• Male pronouns: Male pronouns can be used only when referring to a specific male person. If you want to refer to a single person of unspecified gender, you have several other choices: (1) use "they", which is a grammatically correct, gender-neutral, singular pronoun; (2) use a phrase with an appropriate noun instead of a pronoun, such as "the user"; (3) use the stodgy British-type "one" (I dislike this choice, but it is acceptable).

• Very: Avoid use of the word "very". It rarely adds additional meaning to a sentence.

• This: Avoid unqualified use of the word "this". In many cases, it is grammatically correct to use "this" without a noun or phrase following it. However, in many of these cases the reader must make extra effort to figure out to what the "this" refers. This is not a good idea.

• A number of: Avoid the phrase "a number of", as in "The paper contained a number of awkwardly written sentences." This phrase is vague as to the quantity, or even magnitude, that is intended. Instead, you should use words like "a couple", "few", "several", or "many". These words are more precise and give the reader a better intuition about what you mean.

• Unix-style function names: In the old Unix documentation, written before typesetting was common, Function names were written with parentheses following the name, for example fork(). On old-style printers, with single, fixed-width fonts, the parentheses help distinguish the function names. On today's modern printers and word processors, we are not constrained by fixed-width fonts, so you can write something like fork, instead of "fork()". This style is less distracting and avoids the appearance of parentheses that often run together.

• Precision vs. accuracy: Precision describes how many significant digits you present. Accuracy describes how close you are to the correct answer. More digits do not necessarily add more accuracy and more accuracy does not always require more digits.

• Uses of references in the prose: Avoid using references (citations) as part of your prose. References of the style "[12]" came about because typewriters could not easily generate the superscripts that were traditionally used to reference footnotes. References in the social sciences often appear as footnotes, and not at the end of the paper or chapter. In book typography, this 12 would properly be a superscript. While you might (improperly) see a sentences such as:
The authors in [12] are blathering idiots.
you would never see
The authors in 12 are blathering idiots.
In general, it is more informative to the reader to avoid the need for such structures, since it forces the reader to look up the reference to have any idea of what you mean. A nice way to rewrite this sentence would be
In the recent study by Moe, Larry, and Curly [12], the authors showed themselves to be blathering idiots.
If you absolutely must cite the reference directly, the IEEE journal style for this situation is shown below.
The authors in Reference 12 are blathering idiots.

Last modified: Wed Sep 3 14:39:45 CDT 2015 by bart