Existential Documentation

Let’s be honest.

We lie*.

Sure, I’ll gladly pay you Tuesday for a hamburger today. And of course it’s ok, baby, I’ve had a vasectomy.

Though we are inherently flawed individuals, what with our brains being able to thwart even the most solid evidential findings in favor of “OMG! Sarah Jessica Parker is an alien!” Ignoring that she does look like a foot, however, affords no excuse for our instruction manuals to lie directly to our faces.

Granted, I am a firm (giggity) believer that there should be no reason anyone should not be able to pick up a computer, microwave, food processor, television, game console, or toaster, such that one can’t utilize the device without any instructions whatsoever. Which, in theory should mitigate the need for these fancy-pants novels of inserting peg A into slot B.

How? By making it simpler, of course.

Yet there’s no denying that with each revision of technology, it becomes an order of magnitude more complex. Examples?

Television circa 1970: Connect the antenna to the UHF screws, unless you had cable.

Television circa 2000: Obtain cable box. Attach cable box to component video in and component audio in. Program television color settings. Rename input setting.

Game console circa 1985: Insert cartridge. Push power. If failed, exhale briskly on cartridge contacts and try again.

Game console circa 2005: Power on. Listen to firmware power on noise. Configure video output mode. Configure sound output mode. Insert game disc. Install game. Update game. If failed, attempt same steps again with each video and sound setting. Return game for replacement. Repeat from beginning. Console drive fails. Return console for replacement. Wait two weeks. Repeat from beginning of beginning.

Yet, with all these new fascinating devices and whirling-spinny dervishes, we’re stuck with a manual that in basically any case will end in, “please see your local repair shop or call 1-800-CRAP-FEST for technical support.”

Something seems disturbingly wrong with that.

In most common lines of sane thought, one has to document the procedure they follow to solve a problem. The laboratory researcher keeps diligent notes such that she could recreate the same results and verify the validity of a conclusion. The car mechanic removes brake pads and drums in a specific order, and replaces them with a new set by reversing that order, ensuring that no piece will be overlooked.

The software engineer inserts comments… er… bad example. “But, my code is self documenting.” I covertly lied with great relish. It’s human nature y’know.

The point is, most common problems with our everyday devices have already been solved. With more careful engineering, we could solve the problems ourselves. But give us the documentation. Tell us how to fix it. Explain to me how you wrote this program so I don’t have to come over to your desk and bother you. Document it somewhere and then release it.

In a saving grace, at least the open source community embraces this whole-heartedly. Don’t like how something works? Here’s the guts: fix it yourself. Improve it for everyone. Don’t agree with where this group is going with a project? Split it off and make it your own project.

Just, make sure to include a user’s manual, ‘kay?

  • Honest. No, really.