Information Technology Reference
In-Depth Information
to the price of the software. In fact, the term “shelfware” arose as it was
known to be used to bulk up software delivery packages. As software
was expensive but not really physical, packages were made glossy and
large with bulky user manuals to make the customer feel good about
spending all the money. Even in the mainframe days, senior managers
kept a row of manuals on their office shelves — it looked impressive.
The more clever ones removed the plastic covers from them and dog-
eared some pages randomly.
But why are these documents not considered useful? Is this a phe-
nomenon in the software industry alone? Like most other things, one buys
software on the basis of its features and specifications, not on the basis
of the completeness of its documentation. Have you ever rejected a car
because its user guide was not colorful or a self-assembly furniture unit
because the instructions on it could make sense only to an expert
carpenter?
Software is a bit different. The user has a lot of freedom in interacting
with it. Unlike hardware devices that have a few buttons or dials that can
be moved, software is like an open playing field (Figure 15.1). A simple
input screen or form opens up all kinds of options for a user. A field for
“Name” is open to accepting numbers, characters, pictures, special char-
acters — whatever can possibly be entered using the keyboard and mouse.
The software should not only be able to take care of pointing out the
errors, but the documentation is also expected to be precise and say
exactly what can and cannot be entered. On the contrary, one will not
find too many users manuals for DVD players that say one should not
put a tortilla or pita bread in the CD drawer. It is “obvious” there.
Reference Documentation
Not all documentation generated during the creation of an application
can be considered reference documentation. The term is being used here
with respect to the end user. Such documents could be troubleshooting
guides, cheat sheets, or assembly guides. It is a standard practice to give
some kind of reference documentation along with a release.
The problem with reference documentation, as with most documen-
tation, is the difficulty in striking a balance between overwhelming detail
and practical guidance, between having to cover the many exception
conditions and the normal scenarios.
One way of improving the reference documentation is to watch for
the stick-it notes that users stick to their monitors while using applications
or notes they have written that they keep referring to while using the
screens. These may contain codes and descriptions, short cuts, errors and
how to handle them, phone numbers to contact, field entry tips (do not
