Style in technical writing

April 17, 2012

Several discussions with technical writers have shown me that I hold a very peculiar view: there is a uniform good prose style for technical writing in English. There are distinct voices within that style—no one would confuse Feynman’s writing with Dijkstra’s, nor the section by section layout of Landau and Lifshitz with Unix man pages—but the variations are relatively small.

Let me begin with a series of exhibits of small scale prose style, taken from documents that I have read over the years and that I recalled as clear and informative. Each exhibit is a paragraph or two long, chosen more for its ability to stand alone than for any stylistic distinction.

Edsger W. Dijkstra, EWD1213: Introducing a course on calculi:

“The functions I grew up with, such as the sine, the cosine, the square root, and the logarithm were almost exclusively real functions of a real argument. Sometimes, but not very explicitly, the argument could be allowed to be a little bit more complicated, such as the maximum of two values, a real function defined on a pair of real values, or on two values: whether the maximum was a function of one argument (which had to be a pair) or was a function of two arguments (each of which was a real number) was a question that was avoided. We didn’t talk about the types of the function arguments, we did not talk about the types of the function values either: we did not need to, for to all intents and purposes, all our functions were of type real. (Later this was extended to the type complex, but that was about it.) The net effect was that I was extremely ill-equipped to appreciate functional programming when I encountered it: I was, for instance, totally baffled by the shocking suggestion that the value of a function could be another function.”

Richard Feynman, Cargo Cult Science:

“I think the educational and psychological studies I mentioned are examples of what I would like to call cargo cult science. In the South Seas there is a cargo cult of people. During the war they saw airplanes land with lots of good materials, and they want the same thing to happen now. So they've arranged to imitate things like runways, to put fires along the sides of the runways, to make a wooden hut for a man to sit in, with two wooden pieces on his head like headphones and bars of bamboo sticking out like antennas--he's the controller--and they wait for the airplanes to land. They're doing everything right. The form is perfect. It looks exactly the way it looked before. But it doesn't work. No airplanes land. So I call these things cargo cult science, because they follow all the apparent precepts and forms of scientific investigation, but they're missing something essential, because the planes don't land.”

Rob Pike, Notes on Programming in C:

“I argue that clear use of function pointers is the heart of object-oriented programming. Given a set of operations you want to perform on data, and a set of data types you want to respond to those operations, the easiest way to put the program together is with a group of function pointers for each type. This, in a nutshell, defines class and method. The OO languages give you more of course—prettier syntax, derived types and so on—but conceptually they provide little extra.

Combining data-driven programs with function pointers leads to an astonishingly expressive way of working, a way that, in my experience, has often led to pleasant surprises. Even without a special OO language, you can get 90% of the benefit for no extra work and be more in control of the result. I cannot recommend an implementation style more highly. All the programs I have organized this way have survived comfortably after much development—far better than with less disciplined approaches. Maybe that's it: the discipline it forces pays off handsomely in the long run.”

OpenBSD man page for ln:

“The ln utility creates a new directory entry (linked file) which has the same modes as the original file. It is useful for maintaining multiple copies of a file in many places at once without using up storage for the copies; instead, a link ``points'' to the original copy. There are two types of links: hard links and symbolic links. How a link points to a file is one of the differences between a hard and symbolic link.”

The four passages are obviously written by different people, but examine them again. The similarity of the OpenBSD man page to Rob Pike’s style is unsurprising, since Pike was deeply involved in the early days of Unix. Feynman, though is as much of an outlier as I can think of. His passage is a transcription of a speech, with ‘So’s’ starting sentences are connectors, but examine the feel of it crossing your mind. It is technical prose uttered in a New York accent, but still English technical prose in technical prose’s singular style.

I encourage you to read the full texts from which my four excerpts are taken. They aren’t long. I believe one characteristic imposes this prose style more than any other: throughout each text, its author knew exactly what pattern he wished to conjure in his reader’s mind. Each eschewed jargon except well buttressed by a couple well chosen examples, since free floating jargon abdicates all idea of what the reader shall make of your text. The thought has been arranged into a set of sentences that take the reader nearly as directly as possible through it. The sentences are direct. At the end we are in no doubt what each passage says, though any paraphrase we make is likely to be less direct.

This uniformity in style applies to the larger structure of a piece as well. I mentioned in the first paragraph Landau and Lifshitz’s course of theoretical physics and the OpenBSD man pages. The ten volumes of Landau and Lifshitz are organized into sections of a few pages in length, each covering a particular topic or calculation. Each section represents about forty five minutes of study. They are organized into a handful of chapters for convenience, but there are no further levels of subdivision. OpenBSD’s man pages have one page per command, and in each page a uniform succession of sections describing its use. Feynman’s lectures on physics, are divided into chapters and sections, though of slightly different proportions than Landau and Lifshitz.

Why two levels, again and again? Readers loathe deeply nested organizations. If you don’t believe me, examine your reaction to “Paragraph 3(c) of section 12, volume 324.” Compare it to “section 325, about two thirds of the way through.” Yet we avoid the other extreme. Novels, for example, still use chapters, which are a holdover from the days when books were written on a series of scrolls (chapter derives from the Latin “capitulum”, the word for a single such scroll). Longer novels even add a larger division into “books” or “volumes”, again largely vestigial since most novels are published in one volume today. Chapters, and books for larger masses of material, are guideposts in the books that have escaped extinction by being useful. We may take the degree of organization in novels as an evolved optimum for human use. The breaks serve only as guideposts. There is no reason to expect them to behave differently in technical prose, particularly given the ubiquity of find commands on today’s computers.

The OpenBSD man page shows another important distinction: instruction is separated from reference. The paragraph quoted is followed by a formatted list specifying in detail the arguments the command will take. This occurs again and again: the precise grammar of Algol 60 in section 2 of the Algol 60 report is separated from an purely instructive introduction in section 1; the Particle Data Group’s handbooks are vital references, but make no attempt to explain what the numbers they contain are, merely capture all the details necessary to use them. Attempting to instruct while providing reference material either swamps the neophyte with detail he cannot yet absorb, while denying the expert the details he doubtless needs if he has turned to a text at all.

All this can be summarized thus:

Did you enjoy that? Try one of my books:
Nonfiction Fiction
Into the Sciences Monologue: A Comedy of Telepathy