Writing Guidlines

Last Updated: March 26, 1999
The following are some writing guidelines for my students. In particular, these are things that I will nit-pick on in their thesis. I also recommend reading Strunk and White's book, The Elements of Style.

As a first note, the motivation for all of the following is that technical writing needs to be clear and easy to read. If your reader has to work to figure out what you're saying, then he/she is likely to not bother to figure it out, and stop reading instead. Your goal in writing should be to write clearly in easy to read prose so that the reader will read and understand what you have written.

And remember: much of what follows is my opinion. Your supervisor may have a different opinion (especially on the passive voice issue). Discuss things with your supervisor before you get too far.

Too Many Words
In the movie Amedeus, there is a scene in which one of Mozart's pieces is critised as having "too many notes." This is a common flaw in writing: the writer uses too many words to describe something. In particular, the following are phrases that in general can be simplified without changing the meaning: There are many more such phrases; the above are just ones that I commonly encounter. There is an older Unix program called "diction" that would check your writing for wordy or vague phrases (see the next point). If you have access to "diction", try it out.
Vague "this", pronouns
Technical writing needs to be precise. It is easy to accidentally write things that are ambiguous. The common cases are vague the "this" and pronouns ambiuous.

Consider the following:

What does the "this" refer to? The program running fast, or the program running slow on bad data? Often the phrase can be clarified by a single word: Likewise, pronouns can be vague: What had a bug? The program or fclose? Instead of "it", use "the program" or "fclose" to make things clearer.
Alternate vs Alternative
Alternate means every other one.
Alternative means a second choice.
That vs Which
A common error in technical writing is to use the word "which" instead of "that". A word of caution: there are several styles of usage for "which" and "that". The one that makes technical writing easiest to read is the following: "That" is restrictive, while "which" is non-restrictive. In other words, if you use "that", then the phrase that follows is critical to the meaning of what preceeded. If you use "which", then you are just giving extra information.

An example should clarify this:

In the former sentence, there are more than one bicycle, and we use "that" to select among them. In the latter sentence, the identity of the bicycle has been determined, and we use "which" to give additional information (in this case, the location of the bicycle).

Note that a "which" clause is parenthetical, meaning that it should be contained in commas or parentheses. To determine which to use, see if the sentence changes meaning when you strike the "that/which" clause. If it does, then you should use "that", otherwise you should use "which". Native speakers have a special neural net that gives them another test: Try both "which" and "that" in the sentence, and if both work, then use "that".

Just to complicate things further, the above only refers to one use of "which" and "that". There are other uses of both words (such as with prepositions like "of which", "by which", etc.) for which the above rule is irrelevant.

Write English
A common mistake in technical writing is to use incorrect English. In particular, here are common mistakes:
Passive voice vs "we" vs active voice
I have a theory. A long time ago, scientists were not very objective in their research, and mixed their opinions with facts. Eventually, people realised that this was a bad thing, and there was a strong push to "objectify" scientific writing. The obvious (but incorrect) way to do this objectification is to remove the writer from the writing, and in particular never us the pronoun "I".

If you try writing without "I", you quickly find you (a) must use the passive voice, and (b) your writing sounds as dead as the dinosaurs. It turns out that there is an additional problem with completely removing the pronoun "I": it makes your writing unclear and difficult to understand. In particular, if you write "10 subjects were given the test and...". The question arises: Who gave the subjects this test? Who did this work? That's the curse of the passive voice - it doesn't tell you who the actor is.

One feeble attempt to solve this is to use "we" everywhere that you would use "I". Sometimes, of course, the use of "we" is correct: it may mean the author and the reader, or there may be co-authors. But when "we" replaces "I", it becomes a "royal we," referring to the writer and god (which was probably not the intention of the writer). The "royal we" is probably best left for the exclusive use of Kings who have been dead for centuries.

Further, in a thesis, the use of "we" is strange. This is suppose to be the work of the graduate student, not the work of a committee. Yes, a thesis is often the work of both the student and the supervisor, but usually the supervisor's role is just supervisory, with a bit of guidance and help when needed. Most supervisors are happy to have the student take credit for the work in the thesis (in return for co-authorship on the corresponding paper, of course :-).

So that brings us back to using "I" in technical writing. Again, note that the use of "I" is usually clearer and more objective. The last one may be a bit of a surprise, but if you voice an opinion in your thesis, it is critical to make it clear that this is your opinion (anyone using "the author" to refer to themself is referring to themself in the third person, a definite writing no-no).

The trick in techinical writing is determining when to use "I" and when to use another construction. When in doubt, ask yourself how important it is to both the clarity and to claiming appropriate credit for your work. The thesis is your work, after all, and you should make it clear what your contribution to the work is.w/

Silly Stuff