|
How to avoid writing the documentation: in-line help
Copyright © 2000 Ernesto
De Spirito
Contents
Introduction
In a joke of a past issue of the Developers Newsletter we defined documentation as
"the first thing a user asks and the last thing he reads (if ever)." We
could have also defined it as "the first thing a developer forgets and
the last thing he is willing to do (if ever)."
These definitions may sound like jokes, but they convey the sheer
reality. Well, companies don't have problems: they have technical
writers and they pay them to write (and supposedly they like it), but
for lonely developers or small teams, the facts of life are:
- Users don't want to read the documentation
- Developers don't want/like to write the documentation
- Users claim for the documentation
It seems we (developers and users) would all be happy if it weren't for
the last point. Why on earth do users want the documentation if they
won't read it? Well, first of all, some users want the documentation
because they actually will read it. They want the chance to be able to
do things by themselves without depending on us. However, most users
won't read it, but I think they ask for it for a very simple and quite
understandable reason: fear. Fear of what? Fear of not getting enough
help and support if they get stuck and can't go on with our application
by themselves.
I believe most users that ask for documentation consider it to be the
last resort, and it makes them feel safe to have this resort available
in case they ever get to need it. What they want is guaranteed support,
and they see in documentation that guarantee; a guarantee of quality.
This doesn't mean users are going to read it if they don't get support,
but they want to have something to show to somebody who might be in
position to help them. This means that -either way- eventually somebody
will read the documentation, and therefore we'll have to write it...
Now the facts of life are:
- Users want/need the documentation ==> should be provided
- Developers don't want/like to write it
What is the solution? Somewhere in between: just writing the minimum
documentation possible! ;) Again, it may sound a little bit funny, but
it is actually something very serious. Documentation adds value to a
software product, as it also increases its cost, so only enough
documentation should be written to satisfy the users.
The goal -then- is maximizing user satisfaction to attain the highest
added value while minimizing our efforts in order to keep the cost as
low as possible. Can this be achieved? To a certain extent, yes. How?
Well, there are different techniques for the different parts of the
documentation:
Installation instructions
One the most frustrating things for a user is not being able to install
an application by himself. You can (AND SHOULD) avoid this part of the
documentation by providing a fool-proof installer.
Once I was talking over the phone with a user that asked me for help to
install an application:
- "OK, now double click the file SETUP.EXE"
- "Done. It says 'This will install blah, blah, blah...'"
- "Fine. Click the 'OK' button"
- "Now it says 'Read the terms blah, blah, blah...'"
- "Click on 'I Agree'."
- "Now it says 'Choose the installation blah, blah, blah...'"
- "Click on 'Typical' and then 'Next'."
- "Now it says 'Do you want blah, blah, blah...'"
- "Just click 'Next'"
- "Now it says 'Installation finished, blah, blah, blah, View README?,
blah, blah, blah...'"
- "Click 'No' and then 'Finish' and that's it."
- "It disappeared."
- "Perfect, the installation is finished."
- "Ah... Good, but... Why can't it just install with one single click?"
He's got a point. Most installation wizards are not fool-proof... The
installation program is the first impression a user will have of our
application (and first impressions last forever someone said). A
cumbersome installation won't leave a good impression (users will feel
"it's like the rest") while a simple installation might do wonders with
the attitude of the users towards your application, so it's important
you take this into account when choosing an installer or setting its
options.
Configuration options
Some applications, like email clients for instance, need some initial
data and/or configuration options to be set before they can be fully
operational. You can avoid documenting this if you provide a wizard with
enough visible information on each piece of data requested to the user.
It's a bit disappointing to see many "wizards" and "assistants" that
actually don't provide any assistance at all. A caption saying "Please enter
your name in the textbox below:" tells as much to me as a label simply saying
"Name:". If for instance it said "Enter your name as you want it to be
seen by the recipients of your outgoing mail:" it woul tell me a lot
more. In general, assistants (or wizards) ask one piece of data per
screen, so there is plenty of room to place meaningful descriptions and
even an example.
Tasks/Transactions
I have seen hundreds -if not thousands- of applications in my short
life, and I consider myself and advanced user, but I found many good
looking shareware applications I couldn't use because I didn't know how
to perform certain tasks (like getting started!) and in many cases no
documentation was available... because it comes with the registration!!!
How am I supposed to evaluate an application and know if it will meet my
needs or not if I can't use it? I guess some people need to be reminded
the shareware concept means "try before you buy"... But this is for the
anecdote, the point is that in other cases the documentation was there
but still didn't give me a clue...
The explanation of each menu item, each dialog box, and each control is
necessary, but sometimes not enough. We tend to think that with all this
information it should be obvious to the user how to perform certain
tasks, but reality shows users drown in this sea of information... What
they need is something more direct that give answers to questions in
their own jargon like "how do I record a payment?", and things of the
sort, that are the normal tasks/transactions users have to perform with
our application.
The documentation of any of these HOWTOs can read something like:
- Click the menu 'Tables'
- Click the 'Customers...' menu item. The 'Customers' dialog box will
appear.
- Select the customer whose payment you want to record and click
the 'Payments...' button. The 'Payments' dialog will appear.
- Click 'New...'. The New Payment dialog will appear.
- Enter the data of the payment and click "OK" to record the payment.
Very good, but somebody would ask "Why -instead of making me having to
follow all these steps- don't you provide a button to do all this stuff
automatically?" The user would be right. We can use the scripting
capabilities of help files to automate things like this one, but if we
are going to make the effort of coding, we can do without a help file
having for example a HOWTO menu in our application with a structure like
this one:
Instead of browsing a help file, users can find things quickly this way.
We could also use a dialog box with tabs, combos, options, etc. instead
of a menu. The key here is help the users find what they want to do and
then do it for them. For example, when the user clicks the "How can I
record a payment from a customer?" option, we can show him/her a dialog
to simply select the customer and when he/she clicks 'OK' we can show
him/her the 'New Payment' dialog. Simple and straightforward.
The "meat"
The meat of the documentation is the explanation of each menu item, each
dialog box and each control, as well a glossary to explain (uncommon)
terms. We mentioned before that this part of the documentation is
necessary, but... how much necessary is it? Of course it depends on the
particular application and target users group, but generally speaking,
to avoid writing more than what is needed we can use the ABC scheme:
- 5-10% of the items would require a detailed explanation
- 30-35% of the items may not be obvious, but a reasonably
brief explanation would suffice.
- 60-70% of the items are quite obvious and would require
little or no explanation.
Again, we can avoid writing this part of the documentation using tool
tips that display when the cursor moves over a control, and using
messages that display on a message panel or window when the control is
selected. This requires some programming, but in Delphi and C++ Builder
for example this effect can be achieved in a very transparent and
reusable way.
Summarizing, in the end we have to actually "write" something -it can't
be fully avoided-, but it's a whole different thing. Instead of writing
a complete documentation, to the maximum-possible extent we can develop
our applications in such a way that they don't need documentation (the
best way of documenting an application!) and then we can use "in-line
help" that is cheaper, easier and more maintainable than conventional
help (either printed or electronic), not to say it might be better for
most users since they will see the help right there without having to
press F1 (a key most beginners would never press, for instance).
Of course, there is nothing like a good help system, but in-line help is
an affordable way of providing help for big and small low-budget
applications.
This article was first published in our Developers Newsletter, now discontinued.
|
