November 20th, 2006

The river does not swell with clear water.
-Italian proverb

* * *

In computer programming terms, the good folks who brought you such exciting ideas as interfaces with properties and functions (methods); classes of code; non-linear, event-driven architecture; the Component Object Model (COM), etc., created their own little puddles of jargon that they like to jump into and get your pant legs all mucked up with. These are inexplicable terms that really don't do much to exemplify anything except show the world how clever these developers must think they are by summarizing their knowledge into discrete little bits of word-detritus. And it's more than a little pointless, too, since they have to stop and explain it all in detail to the curious anyhow (it is so tediously inefficient, but they can't see it through their burning angst and anxiety to show you how smart and capable they are). It's like watching them peel out at the green light, and then come upon them thirty seconds later as they wait at the next intersection. Repeatedly.

I know whereof I speak; I work with them to figure out which of their arcane concepts need simplification for users, and which are Not Wanted on the (Instructional) Voyage.

Example? We could easily let an end-user, say an accountant trying to prepare a tax return, or maybe a Marketynge intern trying to create a report about last month's sales, see the following error message (and a developer will often think to himself something like, "They'll need to know this"):

Insufficient free system file handles to execute "SendQueryNamedProc()" in dbmap.dll.

Um ... huh?

Chances are, a better message would be something like this:

Your database is not properly configured. Please consult your system administrator.

Yeah, that second message is a bit better, since it explains in broad terms what is wrong—avoiding unnecessary information that an end-user doesn't give a rat's ass about anyhow—and also what the user should do about it.

I have techie friends who might bristle at what I just wrote. Like most technical people, they seem to think that telling people more information is always a good thing. I mean, if the person knows what you are talking ("talking" is the important word here) about, then by all means, go ahead and tell them what a file handle is, why you need to configure an OS to have an optimum number of them, and while you're at it, remind them to back up their data. But you cannot assume that anyone will know or care what any of it is all about, so let's not just blindly write it into the help file amongst the other information like, "How to print your document" and "Making backups of your data".

If you have identified an audience that might need such information, then publish it in a manual or help file for them. But don't mix your audiences. And don't assume your audience thinks, acts, and talks the way you do.

Think about it this way: You get into your automatic-transmission car. You turn the key, you put it in drive, you press the gas pedal. Intelligent competitive engineering and years of trial and error have evolved a car where you don't have to turn the engine with a crank to get it started. You don't have to manually set the spark advance to match the engine temperature and revolutions-per-minute. You don't even need to know what gear your car is in anymore, since it happily changes gears for you (and probably more efficiently than you can). Furthermore, some cars now park themselves, most adjust their carburetion in closed-loop fuel injected systems to match the type of fuel you put into the tank ... gawd, the improvements are seemingly endless and all lead to a much simpler driving experience.

The owner's manual for your car discusses maintenance and a metric tonne of advertising and marketing, but little about how to actually drive the car any more. This is as it should be.

So why do we think it should be any different with computer software? Just as being told that our oil pressure is 190 PSI as measured at the manifold is meaningless, so does being told there are not enough file handles to complete the SQL query. If we think it is better to have a simple "Oil Low" light on the dashboard, why shouldn't we also think it is better to have a "Contact your system administrator" error message?

Though we may feel that we are smarter and better people for having created a 1,000 page manual about how some piece of software went together with these 378 interfaces and two million lines of code producing 292 error messages, all of which is listed in Appendices A through J, maybe we should instead remember that nobody except maybe our mother is impressed with how much we can write (and how complicated it can be). It is far better to have a 100 page manual that lists how to perform the tasks that the user needs to do to get on with his/her busy day.

Read more rants - Top Blogs - Comment on this rant - Email me