Why don’t they tell you that in the instructions?

“Zen and the Art of Motorcycle Maintenance” by Robert Pirsig is one of those books that you either get or you don’t. It’s one of those works with a loyal following, and most people don’t get it.

I like to think that I get it.

I first read it back in 2000 while bicycling alone from Clarkson University to New York City on a soul-searching trip. One of my professors gave me a copy as a graduation gift. Since then, I must have re-read it in some shape or form at least a dozen times.

A recent conversation with colleagues reminded me of a scene in the book where the protagonist and his friend John park their motorcycles by a diner and go inside for lunch. When they come out, the sun is up, and the day is hotter. John follows the instructions booklet for his BMW motorcycle to the letter and struggles to start it:

I’m started and ready to go and there’s John pumping away on the kick starter. I smell gas like we’re next to a refinery and tell him so, thinking this is enough to let him know his engine’s flooded. 

“Yeah, I smell it too,” he says and keeps on pumping. And he pumps and pumps and jumps and pumps and I don’t know what more to say. Finally, he’s really winded and sweat’s running down all over his face and he can’t pump anymore, and so I suggest taking out the plugs to dry them off and air out the cylinders while we go back for another beer. 

Oh my God no! He doesn’t want to get into all that stuff.

“All what stuff?” 

“Oh, getting out the tools and all that stuff. There’s no reason why it shouldn’t start. It’s a brand-new machine and I’m following the instructions perfectly. See, it’s right on full choke like they say.” 

“Full choke!” 

“That’s what the instructions say.” 

“That’s for when it’s cold!” 

“Well, we’ve been in there for a half an hour at least,” he says. 

It kind of shakes me up. “This is a hot day, John,” I say. “And they take longer than that to cool off even on a freezing day.” 

He scratches his head. “Well, why don’t they tell you that in the instructions?” He opens the choke and on the second kick it starts. “I guess that was it,” he says cheerfully.

— Zen and the Art of Motorcycle Maintenance: An Inquiry Into Values by Robert M. Pirsighttps://a.co/9FWD5cc

Here is the thing. Software Engineering is a stochastic art. Programming is deterministic, but engineering is not. You may very well write your program to the exact specs, but you don’t know the conditions the code will run in. You may follow instructions to the letter, but if you encounter an edge case, will you know what to do?

The motorcycle manual can only account for so many things, and it cannot describe all possible permutations of riding styles, outdoor temperature, humidity, atmospheric pressure, rider’s weight, etc. The manual is only a starting point, but if you own a motorcycle, you need to know how the machine works to grok it.

The nature of our jobs as software engineers is such that we must deal with externalities. Hardware will crash. Services will auto-scale up and down. Garbage collection will occur. Humans will make mistakes and use our software in ways we did not anticipate. Someone will write configuration instructions for you on how to setup your dev environment, and they might not apply perfectly to your setup.

Grok your tools and your craft.