There's a standard university story that goes something like this:
A math/science instructor is deriving a complicated formula on the blackboard. Each
step gets increasingly, hideously convoluted, until the instructor boldly states:
"From here, it is obvious that..."
And writes down a radically simpler formula, seemingly unrelated to any of the previous steps. Upon finishing, the instructor pauses. His eyes dart up to the tangled mess of the previous step, then down to its far-too-distant cousin. The students wait to commit this deus ex machina to their notes, as the instructor, his writing hand still elevated, furrows his brow.
He starts to speak, then catches himself. He looks away from the board, then back again. He begins pacing back and forth in front of the board, examining it from different angles. Suddenly and without a word, he walks out of the room, as the students sit in befuddled silence. Should they leave? Should they wait? After a minute, he bursts back in, and continues:
"Yes, this is obvious. Moving on..."
This happened to me exactly once during my university days. It was an entertaining professor who enjoyed the occasional theatrical moment...but he was also a darn good teacher, and a few minutes later, he rewound the lecture and derived the magical step (with several blackboards full of formulas), and all was right in the world.
In my life as a software engineer, I read a lot of documentation. In that domain, instead of the word "obvious" (which reads as "obvious-to-me-and-if-it-isn't-obvious-to-you-then-this-so-called-documentation-will-be-utterly-useless-to-you") writers substitute the word "easy" or "simple":
Exercise for the reader: search for occurrences of the words easy/easily, simple/simply, and obvious/obviously in your code/documentation. Are any of them necessary? How many you can simply remove or easily edit to obviously avoid these filler words?
It is easy to foo a bar using BazLibrary. You simply use the qux() method.Well, of course it's easy and simple for the writer, whose full-time job is working on the BazLibrary and may even be one of its developers. And it truly might be easier and simpler than the OtherBazLibrary that causes contractors to raise their rates. But it has 50% more words and 0% more helpful content than this version:
To foo a bar using BazLibrary, use the qux() method.Words like easy and simple and obvious are like Ding-Dongs...they're the empty calories of the documentation world.
Exercise for the reader: search for occurrences of the words easy/easily, simple/simply, and obvious/obviously in your code/documentation. Are any of them necessary? How many you can simply remove or easily edit to obviously avoid these filler words?
No comments:
Post a Comment