5.1 -- Examples: Good and Bad Writing

Example of Good Writing

K. M. Chandy and J. Misra, Parallel Program Design: A Foundation, Reading, MA: Addison-Wesley (1988), pp. 290-297

This textbook is an outstanding example of good Computer Science writing. Its topic - UNITY - is completely formal, but the exposition is highly readable.

The exposition is precise. You can always take everything that the authors say literally.

The exposition interleaves intuition with formal description.

The authors have solved a technical problem, and then carefully thought about a logical sequence of steps in which to present their solution. Thus the exposition illustrates the clear thinking that went into the solution.

The chapter presents an algorithm solving a problem using stepwise refinement, which introduces facts for the reader in managable pieces.

Ways in which the text is well written...

(p. 290) The shorthand diners for dining philosophers is clearly introduced.
(p. 290) The text starts out by introducing two concepts that are a key to understanding the chapter: conflicts and conflict resolution. The authors include these because they probably asked themselves, "What concept might confuse the reader?"
(Section 12.1.3) The authors give an overview of the structure of the specification (or algorithm) that solves the problem -- before launching into a discussion of the specification!
(Section 12.1.4) The authors then communicate how they plan to present the design: as a series of stepwise refinements. In this way, they do not surprise the reader later on.
(Section 12.1.5) The authors give an overview of the structure of the chapter.
(Section 12.2.1) The authors first introduce notation, under a separate heading to avoid interrupting the flow of ideas in subsequent text.
(Section 12.2.1) "Universal quantification over vectors ... is to be assumed unless the quantification is explicit." This will simplify subsequent formulas, but retain absolute precision in the exposition.
(Section 12.2.1) Notation shorthand (e.g., u.t ) is precisely defined, and not just used without definition in the later text.
(Section 12.2.2) Section 12.2 is a specification of the problem. Before jumping into the formal problem statement, an informal statement is given.
(Section 12.2.2) The "Note:" illustrates how to handle the insertion of an ancillary fact without disrupting the normal flow of the text. An alternative is a footnote, however journals sometimes prohibit the use of footnotes.
(Sections 12.2.3 to 12.2.6) Each section follows the pattern of stating informally in words only a property, and then giving the equivalent formal statement in symbols. A careful reading will show that the English text has been carefully written to be exactly the same as the formal symbols. The English is keyed precisely to the formal statements by equation names (e.g., udn1).
(Section 12.2.6) As was done in section 12.2.1, a statement is made (under "Notational Convention") to explain that a formal symbol - os - will no longer be explicitly written in subsequent formal properties.
(Section 12.3) The section first informally states the solution (in 12.3.1), then formally restates the solution (in 12.3.2) , then proves the solution correctness (in 12.3.3). It is easy for the reader to see that the proofs are included.
(Section 12.3.4) Section 12.3 ends with a transition section (12.3.4) that sets the stage for section 12.4.
(Section 12.4) Section 12.4 requires understanding of graph edge reversal. Therefore a separate heading ("The Key Idea...") is added to separate and explain edge reversal.

Example of Bad Writing

(Authors Names Suppressed), Parallel Simulation of Communication Networks through Time Segmentation

This paper is written by well known and smart people. I reviewed the paper (hence all the hand-written marks), and it contains a fairly good technical idea. However, the exposition is so poorly written that it detracts from the technical idea.

Remarkably, the authors produced a wonderful second draft!

(page 1) The title misrepresents the paper. The paper presents a method to simulate queueing networks, not communication networks.
(page 9) The paragraph preceding Proposition 2.2 is a good example of how not to informally state a result: The informal statement uses symbols, not English words, thus repeating the "if Ni m2 (0)..." in the formal statement.
(page 11) The paragraph under "Phase 1" contains a classic example of an author defining a symbol (i.e., i ) to mean two different things: "On processor i ..." and "...for i =1,...,I ...." However, I have never seen anyone put both definitions in the same sentence!
(page 8) This page contains a great example of how not to present an algorithm.
1. On my first reading I thought there was no informal discussion of the algorithm. Later I realized that a paragraph two pages earlier (page 6) did give the informal idea, but without an explicit connection between the algorithm and informal text.
2. Some symbols (e.g., M ) are not defined in the preceding text. In step 1, i is not defined.
3. Mysterious formulas appear (e.g., -log(...)/... in step 0), which only the expert reader will recognize. (The formula computes a random variate of an exponential distribution from a uniformly distributed random variate.)
4. The two bullets under step 3 are nearly identical statements - a better way to factor out the common part would improve the presentation.

Class Discussion

What do you like or dislike in textbooks, computer manuals, or articles that you have read in the past?

Can you think of a particularly well written text, manual, or article?