How to avoid writing the documentation: in-line help
Copyright © 2000 Ernesto De Spirito
 |
Contents
 |
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:
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.
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.
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 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.
