Technical Writing for Computer Scientists

Mihir Bellare
Department of Computer Science & Engineering
University of California at San Diego

This document records some reflections and information on the subject of technical writing. It is written for computer science students, who presumably have more familiarity with things like programming than with mathematics, and tries to explain some of what mathematics is about by analogies with things more familiar in computer science.

The views here are entirely personal. They do not reflect those of the university, the department, or other faculty.

What Dirac said

Paul Dirac, a famous physicist, one said the following about a paper written by a colleague: ``This isn't right. It isn't even wrong.''

The worst things you can write are those that don't make sense. If you get it right, well and good. If you get it clear but wrong, at least you can discuss it with others, change it, improve, and get partial credit if this happens to be an exam or homework. But if it does not make sense, you are in a bind. This is a important lesson to learn. One has to put effort into making sure that what one says makes sense. In the domain for which this document is written, this means mathematical sense.

Communication, especially written, plays a central role in understanding the materiel and doing well. A large fraction of the difficulties that one finds student having stem from lack of facility with mathematical language, and writing things that don't make sense. Getting over this hurdle is not only the path to doing better in, say, the class you are now taking, but benefits your whole academic career and beyond. How can one do better here?

Mathematics is a language

The first step to better mathematical thought and expression is to understand that mathematics is a language. Most of you have learned some foreign language at some time; for some of you, that is English. Think of mathematics as another foreign language. It has its grammar, its syntax, and its semantics. When you misuse it, the result is simple: you will not be understand. Worse, you don't even really understand yourself, even though you might think you do. And, if you are not understood on an exam or homework, you lose points, lots of points.

By analogy, if go to a foreign country, and try to ask for something in their language, and don't get it right, what happens? They don't understand you, and you don't get what you want. Same thing with mathematics. Learn the grammar so that you can use it correctly and you will be understood.

Mathematics is easier than most languages because it is quite logical. What makes mathematical sense is not as subjective as you might think.

The main thing to grasp is that it is your responsiblity to communicate clearly. It is not the other person's fault if they don't understand you. It is your job to make yourself clear. Once you see it that way, you start putting in the effort, and things get better.

Many of you want to do research. You will write and submit papers to conferences, and these will be evaluated by a committee who will decide whether to accept or reject your submission. Good conferences have low acceptance rates, like 15% to 25%. It is hard to get your paper in. A crucial aspect of increasing your chances is to communicate clearly. If you misuse mathematical language, the committee will not understand, and will reject the paper. Then, what can you do? Complain? Say they are stupid, and don't understand you? Yes, you could say that, and most authors do, but does it help? Hardly. The paper has been rejected, and nobody out there really cares when you complain. Instead, write the paper well. It is to your advantage to communicate clearly, so try to do so. Same thing for courses, in either homeworks or exams.

Make a clear distinction between what you think and what you write. After having written something, read it with the mindset of someone who does not know what you think. Imagine this person is your enemy, trying to find a flaw. They will stop at the first thing that does not make sense, and throw your work out. You have to make sure the reader has no excuse to do that.

Now the next question is how one can write better. There is no panacea, but here are some things to look for.

Compiling and type-checking

A piece of mathematical writing, such as a solution to a problem in this course, is in many ways like a program. When you have written a program, you will run a compiler. Two things can happen. The compiler says it found an error. In that case, no executable code is produced. You have to fix the syntax of the program. When you get that right, executable code is produced by the compiler. Now, when you run that, it may be right or wrong in terms of solving the problem you are addressing. But, you cannot even get there if you don't get the syntax right, since your code will not compile.

Similarly, when a grader reads your writing, the grader is trying to produce an executable, something that makes sense to run and see whether it is right or wrong. But if you have syntax errors, no executable can be produced. Your writing just does not compile. This is writing that does not make sense, meaning is neither right nor wrong. How can this happen?

Look for the types of errors a compiler looks for. The largest fraction of errors in mathematical writing pertain to undefined variables and type-checking failures. Almost all exams turned in, in undergraduate courses I teach, have such errors in abundance.

An undefined variable is when you start saying things like ``Run M'' but prior to this, M was not mentioned. What are you running? How can a grader understand this? Similarly, people write pseudo-code in which symbols appear out of nowhere. This is code; it won't compile if it has undefined symbols.

Other common examples of type-checking errors are the following, where M is a Turing Machine and L is a language. People will say: ``M is decidable,'' or ``L halts''. This makes no sense. Certain types of operations apply to certain types of objects. Can you add two strings? No. Similarly, can languages halt? No. Only machines can halt. Again, this is familiar from programming.

These issues have nothing to do with the specifics of the subject you are studying. (I have been drawing examples from the theory of computation.) They are purely about mathematics. Once you see this distinction, it is easier to do better regarding them.

Whenever you write something, compile it before turning it in. Make sure there are no undefined variables, and that things type-check. For every object in your write-up ask yourself: what is the type of this object? Is it a string, a machine, a language? Then, look at the operations you do with it. Are these permitted operations?

Understanding versus communication

A common feeling people have and express is: ``I understand what I am doing, but I don't know how to write or say it clearly.'' This is an unproductive point of view. Instead, try to adopt the following view: ``If I can't communicate it, I don't understand it.'' This is more productive. As you strive to communicate, you will understand things better. Understanding is just self-communication, and you have to be clear with yourself too.

The genius who nobody understands is a figure many people look up to. Many of us feel that if we don't understand someone, it is because they are saying very deep things, and they must be really smart. If they were really smart, they would be able to communicate. If you pursue this type of respect, you isolate yourself. In the end, it is detrimental to you, because you loose the critical feedback coming from the need to justify and explain your choices and results, and the quality of your work suffers.

Our thoughts always start fuzzy. That's ok. But, when you want to communicate them in a formal setting, like in a homework, exam or a research paper, don't leave them fuzzy, or they will not be understood.

I'm not saying this is easy. In an exam you have limited time, and of course some of what you say will be fuzzy. Graders make allowances for that. But try to put your first thoughts on scratch paper, and copy on your exam only the final answer, and make sure it makes sense.