Who is your "target audience"?
"No one can write decently who is distrustful of the reader's
intelligence, or whose attitude is patronizing."
E.B.White in The Elements of Style, Strunk and White
The other day I had used as my quotation the notice from the Pool Committee: "Texas State Law requires that children under 14 years of age must be accompanied by an adult." as a starter for dissecting that horrible corollary in "What is Mathematics?" by Richard Courant and Herbert Bobbins:
"If a prime p is a factor of the product ab, then p must be a factor
of either a or b ."
Needless to say, that formulation was demolished. (I think we ended up with something like "A prime dividing the product of a bunch of integers divides at least one of those integers.". I did not include the transition from implication to equivalence, because that is for later. This time we focussed on formulation.) One of my students felt urged to defend Courant/Robbins, and asked "But what was their target audience?"; in doing so he touched a raw nerve and unleashed a passionate sermon on the crime of contempt of readership. I quoted only approximately E.B.White and promised him a copy of The Elements of Style.
If your text is going to be studied by 60 people and by pondering almost an hour about a turn of phrase that saves your average reader more than a minute, your hour has been well-spent. Your text should be as easy to read as possible. But that measure of "easiness" should be relative to what you have to say and not relative to the length of your text. So, if you aim for "easiness" by making your text needlessly verbose or repetitious, you are cheating. If you are sweeping difficulties under the rug by hiding them in vagueness while a crisp formulation would reveal them you are cheating again. There is only one respectable way of improving your text, viz. by being as clear as possible.
All the general advice about writing such as "Omit needless words. is applicable, and most of it can be found in the general literature. Mathematical texts, however, pose their special problems.
Check all your sentences for ambiguity! And if it really matters, ask a non-specialist to read your text to see whether it makes sense. It is really more tricky than you think: in Boeing airplanes one can find a notice saying that something has to be locked "during take-off and landing", which is funny as soon as you realize that you have to stop for a school bus "while loading or unloading of passengers".
Think very hard about the choice of identifiers! Avoid if possible one-letter identifiers that are all by themselves words in the language of the surrounding prose, such as "U" in Dutch and "a" and "I" in English, as they may confront you with unpleasant surprises. (There is a page by David Gries, in which "I" occurs in three different roles: as personal pronoun, as identifier for an invariant and as Roman numeral! Of course, the reader can sort this confusion out, but it is better avoided.)
Be explicit in all your references to earlier theorems: give the number and don't require from your reader to solve an avoidable puzzle. If you instantiate a formula, again, don't present a puzzle, but state explicitly the substitution.
Never assume the meaning of a technical term known if you can give it in a single sentence: the reader that knows the term skips that explanation effortlessly, whereas its absence could present a major stumbling block for someone else.
Indicate clearly the logical status of the paragraphs in your text. The other week I struggled with a text in which the author stated a mathematical fact (that was new for me). For a long time it was quite unclear to me whether I was supposed to provide the proof myself, because the next paragraph just continued with further consequences and considerations, or whether the subsequent paragraph was the proof of the preceding fact. (The situation was aggravated by the fact that the text referred alternatingly to two different pictures. It was most confusing. And all that confusion was so avoidable! I got quite cross with the author.)
Never to write down to your readership is for the computing scientist even more important than for any other scientist. When computers became a commercial product it was essential for industry that its sales force presented these machines as non-mathematical machines that could be used by any one. As a result of these commercial campaigns, research in computing science has been paralyzed by the "rule" that nothing you ever tried should be too difficult for "the average programmer". Slowly at least at the better universities computing science research is digging itself out of that hole. But we should all be aware that publication practice has a greater inertia. We should make a conscious effort to stop writing for morons. As a science, computing cannot be expected to mature as long as its practitioners don't take each other seriously.
Austin, 10 September 1986
Department of Computer Sciences
The University of Texas at Austin
Austin, TX 78750
United States of America
transcribed by Mario Béland