A Curmudgeon’s guide to computer documentation
“You're already in trouble,” the curmudgeon said, looking over our shoulder as we typed the headline above. “I don’t like the word documentation.”
We knew this interview was going to test our mettle. (For those who didn’t grow up with The New Yorker magazine, we should explain that the editorial “we” is intended to impart an air of cleverness and urbanity to our column.)
Just about everyone either knows a curmudgeon or is one, or both. A curmudgeon is someone who takes those things that most of us accept without question, and proceeds to point out their ironies, incongruities, and (if I may use such a strong word) inadequacies. It is never fun to have our illusions deflated, but it is supposed to be good for us. Therefore, though we don’t like curmudgeons, we are supposed to tolerate them.
A certain curmudgeon we know, who is also a technical writer, had “offered” to be interviewed for this column, and we thought it magnanimous and public-spirited to accept, especially because he “offered” not to hold us up to public ridicule if (and only if) we did.
“So what's wrong with the word documentation?” we asked, already feeling queasy about the entire venture. He leapt into the breach.
“Plenty. I think that word is responsible for 50% of the unusable software manuals in the world today. When I need to get something accomplished, I don’t want documentation. What I want is instructions. Don’t ‘document’ the software, just tell me how to make it do what I need it to do.”
“Isn’t that the same thing?” we asked sheepishly.
“Not at all,” he shot back. “It’s a whole different approach. Someone who believes that the writer’s job is to ‘document’ the software is going to go about it like a programmer or engineer, treating every little detail of the software as equally important. What you end up with is an impenetrable document arranged by menu screen, or listings of fields and commands. Procedures, if any, will be inaccessible, jumbled together with pointless detail. This kind of useless manual is being thrown down in disgust all over America at this very instant!”
It’s strange, but just at that moment we thought we heard something like a soft thump from the office next door.
“But if the writer understands,” the curmudgeon continued, “that his or her job is to give the user step-by-step instructions for accomplishing specific tasks, then he or she is almost sure to produce a truly user-friendly manual.”
“So you are recommending a task-oriented approach?” we suggested helpfully.
“That’s the current buzzword, yes,” he replied. “If what you mean by ‘task-oriented’ is figuring out what your users will want to do and giving them simple and easy-to-find instructions for doing it—then Yes.”
“But maybe sometimes a complete ‘documentation’ job is needed,” we parried, thinking of the encyclopedic tomes we had seen weighing down the shelves in software development departments. The curmudgeon was waiting for this, and cut us off.
“For programmers and engineers who have to understand the internals of the software, fine. That’s exactly my point. That is when it is appropriate to talk about ‘documenting’ the software. In that case, your audience needs to know, or at least have access to, everything there is to know. I’m just saying that’s the wrong way to write for the typical end user, who has a very different set of needs.”
We thought for a moment, trying to remember how we got into this, and, perhaps more urgently, wondering whether there was any way out.
“So you think that part of the problem is the word documentation itself?” we asked, in a summing-up sort of way.
“Exactly. You see,” he said, a conspiratorial tone creeping into his voice, “we need to rescue end-user documentation from the death grip of programmers and engineers. And one way to do that would be to stop calling it ‘documentation’. Documentation is an engineering term. Call it a user guide, call it a job aid. Call it instructions or procedures. Any of those are better than documentation, because as soon as we get rid of that term then we—the writers—can take ownership. After all, instructional writers and procedural writers have been in existence a lot longer than computer programmers. And these writers and editors should be telling the programmers what belongs in the user guides, not the other way around.”
“There is no reason to assume,” the curmudgeon continued, “that a programmer has any knowledge of the user’s needs or interests. Think about it. Would you expect the person who assembles kitchen stoves to be able to teach you how to make a chocolate mousse?”
We tried to think about it, but all we could come up with was a menacing image of the Frugal Gourmet waving a welding torch. (Continued)