Whenever the word "documentation" crops up, losers think, "boring;" winners think, "Profit!"
Documentation in its widest sense covers everything written in plain English that comes with your program. It takes two basic forms: obligatory necessities, which most developers cover well, and the supportive information on which few developers do themselves justice.
Copyright declarations, contractual details, warranties, and registration cards are familiar examples of obligatory documentation. Logon directions, help systems, manuals, training systems, Web sites, and coding notes are prime examples of support documentation, although not all of these are needed for all software.
Preparing the legal stuff is largely a matter of finding out the details required and the form they should take. Support matters call for much more reflection. Support documentation can be a huge asset or a serious internal hemorrhage. It all depends on how much real help the documentation provides.
Documentation is the first area that users look to for information. Genuinely helpful information (from the user's point of view, not yours) will tell your clients what they want to know in a way they can understand. This makes your product more enticing, raises satisfaction among purchasers, reduces the number of calls you have to answer from angry users, and generally strengthens your reputation. All of these things add up to money in as opposed to money out.
So documentation is something every program developer should view as a good investment. The effectiveness of supportive documentation determines the following:
♦ Whether sales spread through recommendations
♦ How much additional profit it delivers
Launching a program with set-up instructions that buyers cannot follow is like delivering a fireproof safe without a key. If buyers cannot get the program working easily they certainly won't recommend it to any one else, even if the developer is able to talk them through the installation.
In much the same way, selling a program with a Help system that doesn't offer real assistance turns what might have been a gold pan into a colander. You will be forever answering a barrage of questions and complaints. This not only makes support teams expensive to maintain, but every executive hour spent making up for a deficiency in documentation is an hour in which you cannot build your business.
It is therefore worth spending a little time to understand the difficulties buyers may have with setting up a program with which they are unfamiliar (the same difficulties you may have had yourself with other people's programs). A good way to begin to put yourself in your customers' shoes is to ask your colleagues to hand you a list of problems they've experienced. Here are some examples:
♦ "It's all there but the manual's too thick."
♦ "There's no real intention to help."
♦ "There's too much computerese."
♦ "I've tried and tried the instructions but I just can't make them work."
♦ "I can never remember what is where on the pull-down menus."
♦ "Program writers don't use the same terminology that we do."
How can you make sure that your support documentation won't repeat the same mistakes?
You will have to accept that preparing effective support documentation is a major task. If you are prepared to invest purposeful time and money on it you will save yourself far more costly retrievals later.
Crucial to all this is a strong intention to help your customers. Not even 3R programs can be totally self-evident. While your customer base may include a number of specialists who know more about computing than you do, such experts are rare. Most users will only have a smattering of computer expertise. Some may be new to computing, or if they have an expertise, it lies in another field.
Your users may be old. They may be young. They may not think the same way that you do. English may not be their native tongue. Therefore, your support documentation has to be pitched at a level that engages them all. It has to make sense readily to ordinary and extraordinary people.
Now that manuals have become a rarity, there's also a physiological problem. It's not always possible for users to consult the program and the Help section simultaneously, so there's no direct visual cross-referencing. Unfortunately, as Pavlov discovered, our ability to recall information in the wake of immediate physical movement is exceedingly poor. To be remembered across this scenery change, directions have to be in bites, each no more than a sentence long. Otherwise they won't be held in the human buffer memory while the user shuts down the Help section and reverts to your program.
In essence, this means reducing instructions to road direction terseness. The Help section equivalent of "First left, second right, opposite McDonalds."
Perhaps the biggest single complaint about Help sections is that they unnecessarily reinvent the wheel. Instead of using the terminology customers are used to, they introduce terms and concepts of their own.
Every specialist software program presents pitfalls to a pure technologist, sometimes because the users are diverse, but mostly because each calling has its own vocabulary of technical jargon and established ways of working.
Programmers who fly in the face of established usage can only alienate and confuse their readers. So do so at your peril.
Was this article helpful?