Spence Green

التكرار يعلم الحمار

I work at Lilt. In addition to computers and languages, my interests include travel, running, and scuba diving. more...

Some Remarks on Technical Writing

without comments

For the past year I’ve been improving my writing. More specifically, I’ve been learning how to communicate technical information efficiently and with style. By “efficient” I mean that each word, paragraph, and sentence is contentful, and that thematic strings bind the story together in an accessible way. A reader can use the document as one might use an encyclopedia, i.e. there are elements throughout the running text that help the reader navigate. And by “style” I mean the cultivation of a voice: the arrangement of sentences; the careful use of symmetric; lexical choices. In technical writing, style decisions are made to help rather than to impress the reader.

“Style” in the popular sense should be avoided. In other words, don’t read Strunk and White. Geoffrey Pullum, co-author of The Cambridge Grammar of the English Language, wrote recently in the Chronicle of Higher Education,

The Elements of Style does not deserve the enormous esteem in which it is held by American college graduates. Its advice ranges from limp platitudes to inconsistent nonsense. Its enormous influence has not improved American students’ grasp of English grammar; it has significantly degraded it.

Besides the “limp platitudes,” there are errors in matters of fact:

Some of the claims about syntax are plainly false despite being respected by the authors. For example, Chapter IV, in an unnecessary piece of bossiness, says that the split infinitive “should be avoided unless the writer wishes to place unusual stress on the adverb.” The bossiness is unnecessary because the split infinitive has always been grammatical and does not need to be avoided.

(For more of Pullum’s remarks made with his tie at half-mast, see this post on Language Log)

Instead of guidelines, I have learned techniques that may be applied to a document during the revision process, which should be iterative and extensive. For research papers, here are the best skills that I’ve learned:

  • The result is chief – Dead-ends and negative outcomes are not important.
  • Chronology is not important – Present that which works. The paper represents a shift in form from the lab notebook, which is chronological, tedious, and inappropriate for broader consumption.
  • Don’t obscure the story – Research is revisionist and opportunistic. The result may have been born out of chaos, but the chronicler has the liberty of imposing order on the proceedings.
  • Avoid ambiguity – Readers will assume the worst. Use rhetoric forcefully.
  • Identify novelty – Do not assume that the reader will identify new contributions. Spell it out for him. In flashing lights. This point is especially important for peer-reviewed publications.

A competent guide to the process of revision is Joseph M. Williams, Style: Toward Clarity and Grace.

Finally, much is to be gained through the thoughtful use of statistical graphics. The works of Edward Tufte are in my mind the first and last place to look. His books are beautiful, and full of ideas. In the introduction to The Visual Display of Quantitative Information, he writes

I also sought to design the book so as to make it self-exemplifying–that is, the physical object itself would reflect the intellectual principles advanced in the book.

That aim should stand for any presentation, no matter the medium. For example, if the objective were to capture something ethereal and abstract like the emotional pulse of the Internet, which graphics would we use? Which style of writing? The answer is that no volume of style or graphics would help. We let the Internet speak for itself, as exemplified by We Feel Fine.

In summary, if the goal is to communicate information rather than to use language for artistic purposes, than the principal focus should be the reader and his relationship to the artifact. Around that principal all other choices should be organized.

Written by Spence

May 12th, 2010 at 2:43 pm

Posted in Technical,Writing

Leave a Reply

You must be logged in to post a comment.