by Jessie Gunn Stephens
Software reviewers are, by and large, articulate folk. When a program pleases them, a warm, friendly chuckle seems to reverberate beneath their published prose. But when a program frustrates them, you can practically hear the grinding of their teeth. And the package component most likely to activate that crunching, damning sound against the programs you’re trying to market seems to be the user documentation.
Reviewers like to write about documentation, and an informal survey I’ve been conducting over the past six months indicates that they know a lot, in general terms, about what’s wrong with your documentation and what you should do to correct it. If you’re interested in producing documentation which will impress reviewers as favorably as your software does, perhaps you'd like to know what they have to say.
The most serious complaint reviewers lodge against user documents is that they often don’t properly identify the readers and set out to meet those readers’ needs. Or, do you know who is going to want to use your software to accomplish what in the real world? If you don’t, your user guides won’t be able to fill users’ needs, because you won’t know what they are.
“The guide tells me how the program works,” writes the reviewer, “but what I want to know is what I can make it do for me.” Only other programmers are likely to have much interest in how your program works. Users want to know how to make it accomplish the specific tasks they need done.
To improve your user documents, take the time to form a clear picture, by research if necessary, or personal interviews with prospective users, of who those people are and what they want your software to do. Then, concentrate on instructing them in how to do those very things. Once you’ve clearly identified the users and their needs, it’s much easier to plan and write documents from the user’s perspective, rather than from the programmer’s.
Reviewers become particularly incensed, as I believe most users would, by documentation which fails to take itself seriously. All too often, documentation is a last minute effort, a few pages slapped together just before the package goes out the door. Careless preparation shows; poor organization,inaccurate descriptions, inappropriate humor (at the reader’s expense), typographical and spelling errors, and bad reproduction are all marks of the documentor’s lack of respect for the user.
If you don’t respect your users, don’t expect them to respect you or your product.
The corrective for such poorly conceived and executed documents is, of course, time and effort. Read that as “money,” if your time and effort are worth anything. But remember, a slip-shod product condemns itself in the user’s hand.
Another source of user discontent is the hack-work product which dishonestly disguises itself in plush packaging. You’ve never heard moral indignation until you’ve heard a user gripe about being deceived into judging a user guide by its cover. Of course, we all know better than to do such a naive thing, consciously, at least. But our culture teaches us to consider appearance a valid criterion of quality, in everything from choosing a mate to buying an automobile. Appearances are important in our consumer advertising-oriented society. But no amount of plush packaging can compensate for an inferior product between the covers. And finding trash bound in embossed leather tends to raise reviewer’s blood pressure because it leaves them feeling that someone has deliberately tried to hornswoggle them, and they don’t like it. Can you blame them?
Of course, no one is suggesting that you shouldn’t package your documents as attractively as possible, merely that you ensure that the contents merit their covers. Packaging cannot substitute for quality.
Statistically, the complaint which most often crops up in reviews concerns the lack or inadequacy of examples and illustrations. Even the experienced computerist needs examples when learning to operate a new program, and for the computer novice,examples and practice exercises can mean the difference between learning to use your program at all or shelving it with a curse of frustration and swearing never to buy another product with your name on it.
There’s no such thing as too many examples, too many “for instance”s, “let’s do this toge-ther”s, “let me show you how”s, “this is how it will look”s, and “such and such will appear on your screen”s. You don’t have to be an artist to provide your readers with an image of their display screens. A simple box will do; they’ll catch on to the convention at once. The more you can reinforce prose with illustrations, instructions with examples, and usage with practice exercises, the stronger your documents will be.
“The manual has lots of examples, but at least half of them didn’t work,” gripes the reviewer, his tone resentful and tinged with incredulity. The reader and prospective buyer is very aware of the indictment, even if it remains unwritten: “This guy didn’t even bother to test out the examples in the user’s guide. Think twice before deciding to trust either his document or his software.”
A full-out beta test of your user documents is the only way to assure their accuracy and completeness. To make this test mean anything, you must approach it as carefully and with as much integrity as you do the testing, debugging, and retesting of your software.
The purpose of testing software is not to prove that it works, but to discover the places where it doesn’t work. Test documents with the same goal in mind,and correct the flaws your testing uncovers just as assiduously as you correct software flaws.
The best documents are those which aid the reader. They provide information in logical units and in conventional order. Indexes grace them. Tables of contents map them clearly, guiding readers straight to the information they’re looking for. They frequently isolate technical or other special material into appendices or even separate manuals. Also, such documents are clearly designed for the specific package version the customer holds in his hand.
If your package exists in more than one version, give some careful thought to the need for more than one version of your user documents. It’s not uncommon for an irate reviewer to lambast a package upon finding that the documentation didn’t reflect the version of the software he had in hand. If you modify your package through updates available to customers, be sure you provide updates for their documentation, as well.
Software reviews appearing in computer magazines do impact your sales. You know that they’re written for the most part by computer-literate people, not novice users. Experienced in the use of a wide range of software tools and applications, such writers aren’t likely to think themselves dumb clumsy, or otherwise at fault when they encounter difficulties in the use of your product, particularly difficulties which might have been precluded by more effective documentation. They know what they’re talking about. You might do worse than to listen to them.