A Documentation Dichotomy Explained

Because they're so confusing to most people, statistician John Cook takes a look at wire gauge as a source of departure for explaining how, for example, software interfaces should work:

Wire gauge is a perennial source of confusion: larger numbers denote smaller wires. The reason is that gauge numbers were assigned from the perspective of the manufacturing process. Thinner wires require more steps in production. This is a common error in user interface design and business more generally: describing things from your perspective rather than from the customer's perspective. [bold added]

Image by Sebastian Herrmann, via Unsplash, license.

Cook gives a few other examples of situations in which the way people in an occupation communicate is different from that of their customers. This shows that the problem, strange as it seems, is actually quite common.

Reflecting on his point, a longstanding frustration of mine suddenly made sense. As a computer hobbyist/amateur programmer/power user, I am frequently frustrated by software documentation: It seems always to be geared for either the computer illiterate -- using the "mouse," click with the right-hand button on the rectangle labeled "Start" at the bottom left of your screen -- or someone with a PhD in computer science who hacks away at his own operating system every weekend just for the hell of it. So it's either too obvious to be useful -- or too hard to access for the specific weird problem I have.

This post helped me realize why that's the case and likely to stay that way.

Grandma is never going to have a script not work because she used the wrong kind of quotes around some variable or other, and Linus Torvalds is probably already grinding his teeth from across the country that I'm even bothering with a shell script for what I'm doing.

The problem for people like me is connecting with people who know the nitty-gritty, but who also understand this communications problem at least on a gut level. That is, I have to find experts who are good at communicating across a context gap.

I am happy to say that, without fully realizing it, I solved this problem years ago, thanks in large part to the legions of open source software developers and enthusiasts around the world. It is usually the case that someone else has asked and had answered a problem similar enough to my own that I can search for and find the answer.

And, on the handful of occasions I have come up empty, there are places to throw the question out there and get an answer. Back in grad school, I had a question like that and got an answer from someone in Iceland within an hour. More recently, I asked nicely for (and got!) a feature added to software I use that I was pretty sure would be easy to add, but had no idea how to do it myself, because it was in a language I don't know.

Why do I post about a problem I have already licked? In part because I didn't realize I'd solved it already and in part because Cook's post helped me realize that, in many cases, the kind of documentation I'd always dreamed about is niche-market at best -- which is why there aren't coherent compendia of it anywhere. But it often does exist in bits and pieces, and it is easy enough to make more of it exist in the manner I just described. So there's satisfaction at realizing the solution I wanted simply didn't appear in the form I had imagined it would. Also, at least in my case, knowing there are good reasons for a state of affairs can often make that state of affairs much less annoying. (And that goes for wire gauges, too!)

All this isn't to say There's no such thing as mid-level documentation. For common uses, there most certainly is, although an outsider might have difficulty finding it for want of knowing where to look.

-- CAV