The Wisdom of Greg Wilson

I'm writing a book at the moment, on Test-Driven Data Analysis. It's my third book, and first solo effort. I sometimes consider calling myself “worst-selling” author, Nick Radcliffe, as one of my previous two books, Getting Started with Fluidinfo, written with worst-selling co-author Nicholas Tollervey, was about a rather visionary online database developed by a friend, Terry Jones.¹ Unfortunately, Fluidinfo shut down at almost exactly the same time as the book was released, which I like to think hurt sales. I don't know how many copies it sold—possibly dozens—but let's just say O'Reilly haven't been banging at our door asking for Volume II or an update. The other book was all the way back in 1996—Sustainability: A Systems Approach, witten with Tony Clayton, written for WWF Scotland. It was commissioned by the late, great, and dearly missed Simon Pepper about this idea we had that humans were messing up the planet. (Don't worry, more than half of humanity's greenhouse gas emissions have come since we wrote the book, and everything seems fine, so I guess we were Cassandras).

The other day I ran across an article by Jess Haberman and Greg Wilson called Ten simple rules for writing a technical book. On the one hand, I didn't really want to look because I'm already 90,000 words in. But I have known Greg for over 40 years, and he is extremely wise, has taught me many important lessons (see below, we'll get there eventually), has written and edited well over a dozen books and is always often right.²

Jess and Greg's article is really good and if you ever write anything technical, you should definitely read it.³ I'm going to take issue with one of their subpoints, and to a subpoint of that subpoint, but that shouldn't detract from the fact that the article is excellent and they're probably also right about the things I will take issue with.

The article's sixth rule is “Avoid common mistakes”, and the last bullet point in the rule is “Don't try to be funny”. I'm going to assume that their rules are a priority-ordered list, so feel dispensation to ignore this because their second rule is Read, then write. This includes the advice “Go through two or three of your favorite technical books and make notes about what their authors have done well …” I've read an unfathomable number of technical books over the last half century, and almost without exception the books I have learnt from best have used humour, often not just in an incidental way but as a device that contributes fundamentally to the teaching and learning. I give a lot of talks, sometimes teach, and blog sporadically and I find humour to be one of the most effective ways of holding attention, regaining attention and passing things on a memorable form. (And yes, of course talks and blogs are different from books.) If I'm giving advice or trying to explain something to someone, there is a very high chance I'll try to exploit humour in doing it. We all lean on Randall Munro for standard pointers to key insights:

• SQL injection — Exploits of a Mom/Little Bobby Table
• Standards proliferation — Standards
• Spending too long on tooling — Is it worth the time?
• Type I and type II errors — Error Types
• Kinetic energy — Relativistic Baseball.

Who ever explained the downside of regular expressions better than Jamie Zawinski in his email signature c. 1997:

Some people, when confronted with a problem, think “I know, I’ll use regular expressions.”

Now they have two problems.

— Jamie Zawinski⁴

Or take Ginsberg's cod version of the Laws of Thermodynamics:

0: There is a game. (consequence of zeroth law of thermodynamics)

1: You can't win. (consequence of first law of thermodynamics)

2: You can't break even. (consequence of second law of thermodynamics)

3: You can't even get out of the game. (consequence of third law of thermodynamics)

Is that actually how I remember which law of thermodynamics is which? Why yes it is, since you ask.

I could go on for days, but I'll just mention one more. Nearly forty years ago, when we worked together, Greg used to say something his father used to say to him:

You know, two weeks of typing can save an hour of thinking.⁵

— Greg Wilson

This is the very phrase I use today when trying to persuade people to delay writing code until they've thought a little more about the problem.

The Don't try to be funny advice, ends by saying “be sparing in your use of bold, italics, and underlining, and remember that nobody reads footnotes.”⁶ I believe it was the unsuccessful Republican contender, Barry Goldwater who used the slogan “In your heart you know he's right.” We don't have the counterfactual, but circumstantial evidence suggests that the response of the wags—“In your guts you know he's nuts”—might have had the effect of successfully undermining Goldwater's message. Either way—even accepting that the point might be overstated for emphasis, and possibly included as a humorous aside—as someone who almost always reads the footnotes (sometimes even the endnotes), it's hard for me to know how to process this claim.⁷ As someone writing a book that's, in some ways, all about attention to detail and going the extra mile to get the right answer, I suppose I hope that even those readers who don't read the footnotes at the start would by the end.⁸

Maybe Jess and Greg aren't actually arguing against including footnotes. After all, to my mind, one of the benefits of footnotes is that they allow you to keep pedantic and marginal details⁹ from breaking the flow of the main text too much while putting in necessary qualifications. Maybe that's what they mean. Put them in, secure in the knowledge that no one almost no one people who don't want to will not read them.

Funnily enough, sparing use of italics was one of the bits of early advice I received from Greg. I asked him about the relative merits of italicizing a whole phrase and of italicizing only the operative word. He advised strongly in favour of the latter “if italicization is strictly necessary.”

Write for Edge Cases #

Another lesson from Greg that has stood the test of time arose when I was struggling with a bug in my code. I don't remember the details, but it involved iterating over some kind of data structure and as we struggled to understand what was going on, Greg said something like “What if we try it with an empty structure? After all, there's really no reason the code shouldn't work with an empty structure, is there?” Throughout my subsequent programming life, I have found this, and its generalization—which I think of as something like take care of the corner cases, and the main case will take care of itself—have been among the most sucessful strategies for writing better code. Corner cases are not only for tests.

Greg has had an amazing career, much of which I don't even know about, but running through all of it has been a strong commitment to education. He founded both the Summer Student Programme and the M.Sc. programme at EPCC, created Software Carpentry (which grew into Data Carpentry, and The Carpentries), co-wrote PEP218, which was the PEP that added sets to Python, and, as I already mentioned has written and edited dozens of books and articles.

Greg: thanks for the advice in the article, and for all your wisdom, enthusiam and effort over the years. Long may it continue.

Endnote #

This article probably reads like an obituary. It isn't. I just thought I'd write the sort of apprecation of Greg that I occasionally write for people when they die. There's really no reason to wait till they die to let people you appreciate know that they're doing something important.