Writing

From the Data Curation Lab @ University of Toronto: tips for writing about computer science research in English.

Strunk and White’s The Elements of Style is a great starting point for CS writers. When you deviate from the rules, be sure it is intentional and that what receives attention is your ideas, not your writing. For an essay on how good writing in English differs from other languages, see Zinsser’s Writing English as a Second Language.

Rules of thumb

• Make definite assertions. Avoid tame, colorless, hesitating, non-committal language (Strunk’s Elements of Style).
• Simple sentences are effective. Avoid long, convoluted phrases. In technical writing, simple sentence structure enhances clarity.
• Be consistent in your writing style. Do not switch between different notations or conventions within one paper.
• Use on-line resources: Strunk’s Elements of Style, American Heritage Book of English Usage, Webster’s Dictionary and Thesaurus. A good book: Bugs in Writing.

Using citations

• A citation is an annotation for a sentence, not part of the sentence; it should play no grammatical role. 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].”
• Prefer author initials and year (e.g. [AO72]) over cryptic numbers so readers can remember references.

Good mathematical writing

See Knuth, Larrabee, and Roberts, Mathematical Writing. Brief pointers:

• 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 notation with multiple or nested sub- or superscripts.
• Do not use notation for the sake of notation; often prose is clearer.

Common mistakes

• Gerunds and infinitives are not interchangeable. Use them correctly (e.g. “required the user to implement” or “required the implementation of”; “involves implementing”; “managed to implement”). See gerunds and infinitives and Purdue OWL.
• Compound modifiers and compound nouns should be hyphenated to avoid ambiguity (e.g. “binary data-structure” vs “binary-data structure”). See compounds.
• Bullet lists: punctuate consistently; use consistent structure in each item; if the list contains full sentences, do not start it with a colon.
• Enumerated nouns: capitalize consistently (e.g. “Figure 1,” “Function f,” “Equation 32a”) or not at all; do not switch.
• How and what are not interchangeable. How is not a pronoun. Right: “what it looks like” and “how it looks.” Wrong: “how it looks like.”
• A preposition is not something to end a sentence with.
• So-called means “commonly named” or “improperly named” (negative connotation), not just “named.”
• On the other hand should be used sparingly and never for more than two alternatives.