Computer Science Writing
The following is an incomplete list of some writing tips that I find
useful for writing about computer science research in English.
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
definite assertions. Avoid tame, colorless, hesitating,
- 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.
- A good book on writing: Bugs in Writing
- 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
- 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
Good Mathematical Writing
A thorough resource is the Knuth, Larrabee, and Roberts book
Writing. A few brief pointers on common mistakes are given
- 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
- 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.
- 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
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
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
(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.
- 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.
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
- 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
- First, we prove that quasi-lunar is equivalent to
- 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.
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.
- See Figure 1 in Appendix A.
- We will use Function f in Equation 32a.
- In our experiments, Iguana 17 performed very well.
- 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
- 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