Archive for the ‘Writing’ Category

“Literate” Programming, Technical Writing

Friday, March 16th, 2007

There’s been some recent discussion on ruby-talk about “literate” programming after the new O’Reilly title Beautiful Code was announced (Matz has written an essay for it). Matz’s response made me listen to all-things-Knuth, so I was pleased to read Philip Wadler’s post today on Three ways to improve your writing, which includes a PDF link to Knuth (and others) lecturing on writing and “literate” programming. I’ve just started reading it, but have already found two laugh-worthy gems:

13. Many readers will skim over formulas on their first reading of your exposition. Therefore, your sentences should flow smoothly when all but the simplest formulas are replaced by “blah” or some other grunting noise.

20. Some handy maxims:
Watch out for prepositions that sentences end with.
When dangling, consider your participles.
About them sentence fragments.
Make each pronoun agree with their antecedent.
Don’t use commas, which aren’t necessary.
Try to never split infinitives.

I know the first is certainly true for me as I’ve been trying to wade through Haskell (a language into “literate programming”) introductions recently, which are very math-heavy.