We moved into a new house last month. If any of you have bought a house before, you know that it ends up kicking off a whole host of projects.

This weekend I retrofit five fluorescent light fixtures in the new house to take LED “bulbs.”  This involves some simple wiring — once you figure it out. Figuring it out was the hard part for me.

I spent 8 years in the Army as a second level support Radar repairman. This required almost a year of electronics training. After I left the Army I spent 2 years working in electronics, including a stint helping design microprocessor-driven manufacturing systems. (We call them “robots” now.)

I couldn’t figure these instructions out:

instructions

Finally I did some Internet searches and found this sentence.  (In a forum that I can’t link to directly.)

Short the ballast out, and remove the starters.

This involved clipping the wires on either side of a now-unnecessary component inside the fixture and connecting them too each other, and then removing the starters for each bulb.

It was obvious. Why didn’t the instructions just say that?

In a previous life I was a dog trainer. I had a mildly popular blog (no point in linking to it, I took it down.) At one point I wrote a series of posts that reviewed episodes of a dog training TV show that many trainers find objectionable. I decided to take the approach of actually reviewing the show, both good and bad, rather than what had been the standard approach of only discussing the bad.

As I watched the show I noticed that while many of the things that the TV trainer had his students doing were unnecessary or even outright undesirable he was really good at getting them to do them.  If he wanted them to hold the leash tight (ugh) they held it tight. If he wanted them to make eye contact, they made eye contact. I don’t mean he was a master of persuasion — I mean he was (is) an excellent coach.

This was something I was struggling with and was ultimately one of the reason I left training. I paid close attention to how he handled students and for a very long time had a post-it on my desk at home:

Don’t be afraid to point out the obvious.

When he coached a student he would point out, in very direct terms, what was happening, what was going wrong (in his opinion), and what was going well. When he needed them to do something he explained it and repeated it if necessary. I had a problem with this. When I stated the obvious I felt like I sounded like an idiot (after all I was belaboring the obvious!) or a nag.

Now “obvious” and “simple” are not the same thing. We developers can have a tendency to get bogged down in details and oftentimes a nice dose of simplicity to the forehead can be exactly what the doctor ordered, but that’s a different story.

What’s obvious to you might not be obvious to someone else. Don’t be afraid to add it to your documentation. Don’t be afraid to add a comment to your code.

What inspired this post was some documentation I read today that, while providing excellent (and actually quite simple) configuration instructions for some new software I needed to use,  never told me why I would ever need to configure it that why. Why I found out it was….obvious.