Why should we waste money on documentation? Nobody
reads the online help or the manual anyway.
The fact that this fallacy is so widely believed doesn't make it
any truer. It can be refuted with a simple question: What percentage
of software users actually contact support? I'm willing to bet that
it's a small minority of the total. That means that the majority
of your users are managing to use your programs without asking for
additional help.
Also, good documentation is not expensive. On the contrary, it
saves money by reducing support overheads. Everything that's explained
properly in the online help and other documentation only needs to
be dealt with once. After that it takes care of itself. Everything
that's confusing or left out has to be explained again and again
by your support staff. And again. And again. And again. Or you have
to post additional answers and how-to instructions on your web page,
where many users will have trouble finding them.
Good documentation enables you to make your support team accessible,
radically enhancing both your image and user satisfaction. Overloaded
support desks have to be barricaded against the users they were
created to serve, with multi-tier access systems, busy signals,
automated robot answers and voice mail. Most users have plenty of
frustrating experience with all these systems, and they hate them.
If you can reduce support requests to the point where you can offer
direct responses you are already far ahead of the pack. Good documentation
helps to make this possible.
Nobody knows our application better than the programmers.
Why should someone from outside write the help files?
The main answer is in the question. The programmers know the programs
too well. They can’t see the woods for the trees. In a way,
their intimate knowledge of the application makes them ignorant
– ignorant about what someone unfamiliar with the program needs
to know. With few exceptions, ordinary users generally find help
files written by programmers infuriating and frustrating.
In contrast to this, an experienced help author dealing with the
application for the first time must go through exactly the same
learning experience as the future users. If he/she does his/her
work properly, the help author will document the entire learning
process, guiding the user through it and providing easily-understandable
answers to all the questions that crop up along the way.
Are there any other reasons why the programmers
shouldn’t write the help files?
Yes. The most important one is the cost. Programmers are a very
expensive resource that needs to be deployed as efficiently as possible.
Writing documentation is generally the last thing they want to do,
and since the results they produce are usually counterproductive
it doesn’t make sense to make them unhappy and waste their
time and your money by having them do it. Also, when they're writing
help files they're costing money instead of making it. In the time
they waste writing bad help files they could be producing more good,
marketable code. Makes sense, no?
The examples you showed us
all use HTML Help. What about other help formats like WinHelp, Java
and straight HTML?
I don't do Java, but if you want WinHelp or straight HTML I can
produce them, no problem. Generally, however, I strongly recommend
using HTML Help for modern Windows applications. HTML Help looks
slick, is highly-customizable and very user-friendly. Now that powerful
and efficient HTML Help authoring tools are available it's also
just as easy, or easier, to produce good HTML Help as good WinHelp.
What's wrong with WinHelp? It's supported by all
Windows versions without exception, isn't that a big advantage?
WinHelp is an antiquated system with origins dating all the way
back to the 1980s, and it shows. WinHelp files generally have a
clunky "look and feel" that detracts from the appearance
of graphically attractive modern applications, and the restricted
navigation capabilities are annoying for most users and frustrating
for neophytes.
In any case, the only Windows versions that don't support HTML
Help are Windows 95 and very early versions of Windows NT; and even
they can do HTML Help if they update to Internet Explorer 4 or higher.
Unless you're specifically targeting Windows 95 and NT users who
haven't updated their systems for years there is no longer any reason
at all to continue using WinHelp.
Look at it this way: The vast majority of Windows users now have
systems that will support HTML Help. Do you really want to give
all these users, who are generally better customers (they're using
the more modern systems), an inferior help system for the sake of
a tiny minority of customers who are clearly either unwilling or
unable to shell out for the occasional update? It's simple mathematics.
Sure, but what about all the people who don't want
to have Microsoft® Internet Explorer on their systems?
We're building applications for Microsoft Windows®, right?
Like it or not, Internet Explorer is pretty much part of the Windows
operating system. Nobody forces you to use it, you can browse with
Opera or Netscape or even Lynx if you want, but IE has to be there,
and having it there is absolutely no problem on modern computers
with huge hard drives.
Over the last couple of years this argument has also become a non-issue.
For example, one of my clients, a software company producing mass-market
Windows applications, switched to HTML Help a little over a year
ago. Do you know how many complaints their help desk has had since
then? Zero. Not one user has contacted them saying that they couldn't
display the HTML Help files. Case closed.
What about all the other
options, like browser-based HTML and so on?
There are definitely a few situations where using browser-based
HTML might make sense, for example if you are distributing CD-based
applications where you want the users to have access to the individual
files, or for web-based help systems that let you update individual
topics quickly. Otherwise, I've been completely underwhelmed by
all the alternative help systems I've seen so far — including
those by the big hitters like Adobe and Macromedia. Some of them
look quite good but they don't work as well or as quickly as HTML
Help, and they force the user to learn to navigate yet another new
system without providing any functional benefits.
I suppose that companies that produce web editors would feel that
they were losing face if they didn't program their help in HTML.
Even so, the bottom line is, why invest unnecessary, and large,
amounts of time and money in inventing an inferior wheel?
What about web-based help systems that keep us
in contact with the customers and let us update components instantly?
These are great if you're only targeting customers in the USA,
where almost everyone can be online all the time at no extra cost.
Everyone else in the entire rest of the world hates these systems.
You have to remember that outside the USA almost everyone still
pays for Internet access by the minute, and in most countries it's
still not cheap. If you sell your customers a system that costs
them money every time they access Help they're really going to love
you!
It's really important to factor this in when you're developing
applications for an international audience. (And it doesn't make
it any better that this is something that most browser vendors and
major software manufacturers still ignore.)
