Computer Science Writing

First, a bit about my writing style. Strunk and White "The Elements of Style" is a great starting point for CS writers. Yes, it is prescriptive. But you need to know the rules, even the small rules about when to capitalize and where to put commas. When you deviate from the rules, you draw a reader's attention. Be sure this is intentional and that what is receiving the attention is your ideas, not your writing.

This advice is very specific to English CS writing. For a insightful essay on how good writing in English differs from other languages, I recommend Zinnser's essay "Writing English as a Second Language".

Rules of Thumb

• Make definite assertions. Avoid tame, colorless, hesitating, non-committal language.
• Simple sentences are effective. Avoid long, convoluted, perhaps even warped, phrases that twist, turn and distract from the point one might wish, in this ever-so literary of worlds, to make in the most elegant way possible. Do not use long sentences with complex grammar just to show that you can. Particularly in technical writing, simple sentence structure Strunk's Elements of Style explains enhances clarity.
• Be consistent in your writing style. The style should not distract the reader from the concepts you are trying to communicate. Never switch between different notations or conventions within one paper.
• Make use of on-line resources.
  • Strunk's Elements of Style explains some of the basics of good writing style.
  • The American Heritage Book of English Usage is a searchable repository of usage, grammar and style information.
  • Webster's Dictionary and Thesaurus is convenient when picking up your own dictionary is not.
• A good book on writing: Bugs in Writing

Using Citations

• A citation is an annotation for a sentence. It is not part of the sentence and should play no grammatical role in the sentence. In other words, if you remove the citation, the sentence should still be grammatically correct and complete.
  • Wrong "Thirty-second quasi-lunar normal form is defined in [AO72]."
  • Wrong "[A072] contains a definition of..."
  • Right "Alpha and Omega defined thirty-second quasi-lunar normal form [A072]."
  • OK "Many researchers have studied these normal forms [A072,ABC00,XYZ+80]."
• Unless required by the restrictions of a journal or conference, use more than cryptic numbers for citations. It is hard for a reader to remember the meaning of Reference 42. This forces her to repeatedly look this up as she is reading. If you use the more common convention of author initials and year (e.g., [AO72]), it is much easier to remember common references.

Good Mathematical Writing

A thorough resource is the Knuth, Larrabee, and Roberts book on Mathematical Writing. A few brief pointers on common mistakes are given below.

• Do not start sentences with symbols, even capitalized symbols.
  • Wrong R1 and R2 are disjoint. f is a total function.
  • Right The relations R1 and R2 are disjoint. Function f is total.
• Avoid using notation with multiple, or (horrors!) nested, sub- or super-scripts.
• Do not use notation for the sake of notation. Often, it is clearer to use prose.

Common Mistakes

• Gerunds and infinitives are not interchangable! Both can be used as objects, but some verbs take gerunds, some take infinitives, and some can take infinitives with an agent. Use them correctly.

  For example, "The experiment required to implement" is wrong, but "The experiment required the user to implement..." is fine, as is "The experiment required the implementation of..." Also, "The experiment involves to implement..." is wrong, while "The experiment involves implementing..." is correct.
  In contrast, "I managed to implement..." is correct, while "I managed implementing..." is not.

  Some useful links: www.iei.uiuc.edu/structure/structure1/gerinfvbs.html and owl.english.purdue.edu/handouts/grammar/g_verbals.html (or google "gerunds and infinitives").

• Compound modifiers and compound nouns should be hyphenated appropriately to avoid ambiguity. For example, "binary data-structure" and "binary-data structure" mean two different things. "Binary data structure" is ambiguous.

  See: webster.commnet.edu/grammar/compounds.htm.

• Bullet lists are over used by many CS writers. They can be effective for drawing a reader's attention to a set of important statements. However, they are not an excuse for writing abbreviated or sloppy prose.
  Bullet lists should be punctuated consistently. Use consistent sentence or phrase structure in each item. If the list contains full sentences, it should not be started with a colon.
  • The following is wrong:
    • First, we prove that quasi-lunar is equivalent to semi-solar.
    • We also consider solar flare designs showing them to be
    • frequent; and
    • proving such designs are numerous.
  • The following is a correct statement of our contributions.
    • First, we prove that quasi-lunar is equivalent to semi-solar.
    • Second, we show that solar flare designs are both frequent and numerous.
• Enumerated nouns should be capitalized consistently for all nouns (this is preferred by convention in most CS forums) or not at all. Do not switch back and forth on a whim. Some examples include the following.
  • See Figure 1 in Appendix A.
  • We will use Function f in Equation 32a.
  • In our experiments, Iguana 17 performed very well.
  If you feel that such capitalization is unwarranted or arbitrary, more power to you. However, this conviction is not a license for being inconsistent. If you refuse to capitalize Iguana 17, then you may not capitalize Section 2.
• How and what are not interchangeable. How, unlike what, is not a pronoun. Hence, how can not be used to represent a noun or noun phrase.
  • Right "what it looks like" and "how it looks".
  • Wrong "how it looks like". For example, "We now describe how the process will look like in this situation."
• A preposition is not something to end a sentence (or a phrase) with. (Remember that 'to' is often used as a preposition unless one knows more than one ought to.)
• So-called means "commonly named" or more often "improperly named" (and thus carries a negative connotation). It does not just mean "named".
• On the other hand is a rather pedestrian phrase that should be used sparingly in scientific writing, if at all. It should never be used to present a set of more than two alternatives unless you come from a planet of three handed people.