Writing Resources

Computer Science Writing Advice

The following is an incomplete list of writing tips that I find useful when writing about computer science research in English. Please keep in mind that this article is full of my opinions and preferences. Some slides from a talk I give on CS writing.

First, a bit about my bias. Strunk and White “The Elements of Style” is a great starting point for CS writers. Yes, it is prescriptive. Nonetheless, you need to know the rules, even the “small” rules about when to capitalize and where to put commas. When you deviate from expected rules, you draw a reader’s attention. A reader’s attention is a precious gift, not to be wasted. In scientific writing, you want your ideas to receive the attention, not your writing.

This advice is very specific to English CS writing. For an insightful essay on how good writing in English differs from other languages, I recommend Zinnser’s essay “Writing English as a Second Language”. Many of Zinnser’s tips for journalists apply to computer scientists. Simple words and simple sentences are powerful!

Some other favorite resources: Simon Peyton Jones has slides and video on how to write a great research paper and Margo Seltzer’s slides on how to give a good talk.

Rules of Thumb

Using Citations

Abbreviations, Initialisms, Acronyms

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.

If you are expressing one idea per sentence, then a footnote belongs at then end of the sentence after the period (with no space between the period and the footnote).

Common Mistakes

Gerunds and infinitives are not interchangeable! Both can be used as objects, but some verbs take gerunds, some take infinitives, and some can take infinitives with an agent.

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.

For more information, search for “gerunds and infinitives” on the web.

Uncountable Nouns. Some nouns (like information, knowledge, research, and advice) are considered uncountable in English meaning you cannot count them by writing one information, two informations, three informations, etc.
Most nouns are countable, so I can say one algorithm or two algorithms. A rule of thumb is that for uncountable nouns, you do not make the plural (“knowledges” is wrong), you do not use them with the article a (“a knowledge” is wrong), and you use them with singular verbs even you are using them in a collectively plural sense (“knowledge are ellusive” is wrong).

The same comment applies to the use of the word ‘work’ when applied to a body of research. Note that when work is used to apply to a unit of something, then it is countable. The sentence “We saw two works of art by Rodin” is correct.

Notice that I changed the adjective. Since work is uncountable in the context above, use an adjective that is not associated with enumeration (like numerous). Saying “We saw numerous works of art by Rodin” is certainly correct.

There are lists of uncountable nouns on the web. Note that in modern usage, data (like dust) is uncountable. In the past, you might read “a datum is” or “many data are”, but in modern use we have adopted the (formerly plural) word data as an uncountable noun that is used with a singluar verb (like information).

See a favorite essay on Big Data which explains the adoption of data as a mass noun.

Compound modifiers and compound nouns should be hyphenated appropriately to avoid ambiguity.

Here is another example for computer scientists.

See: www.dailywritingtips.com or search for “compound modifiers and hypens”.

Bullet lists are over used by many CS writers (including in this blog). 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. You should use consistent sentence or phrase structure in each item. If the list contains full sentences, it should not be started with a colon.

If the items in your bullet list contain a single phrase then it can start with a colon and be punctuated by semi-colons.

If the items in your bullet list contain more than one sentence, then it should be introduced by a sentence (ending in a period), and each item should contain a set of sentences (starting with a capital and ending in a period). In this case, there is no “and” before the last bullet. My advice is to use a similar construction in each bullet.

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.

A reason for this is that the capitalization is a visual clue that the number or symbol following the noun is part of that noun. This makes the sentence easier to parse for a reader.

If you feel that such capitalization is unwarranted, more power to you. However, this conviction is not a license for being inconsistent. If you refuse to capitalize Iguana 17, then why are you capitalizing Section 2?

Note that section or chapter are not special words in English that are always capitalized. They follow the same rules for capitalization as regular nouns. We often see them capitalized in science writing because they are often enumerated.

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.

Some minor pet peeves of mine (but I may be old fashioned).

Latex advice for my students