Information Technology Reference
In-Depth Information
necessarily been the best when it comes to writing documents,
especially for end users. This has changed over the years, and
technical writers and subject matter experts are used most often
these days.
Documentation is usually organized linearly. This is not how most
people use software. Because you can jump from one screen to
another or click on any of the multitude of icons on a screen,
users expect hardcopy documentation to follow the same stream.
Online help and online documentation are preferred over printed
user manuals. Not only does it make the accessibility to the
document much easier (not having to walk to get a physical paper
manual), but it also makes the help context-sensitive and thus
faster (rather than having to open a paper manual to the “right”
page). Here we have faltered in two of the most basic requirements:
(1) that software documentation is written with the end user in
mind, and (2) that it is supposed to be illustrative.
Software documentation should be more illustrative; it should have
examples of usage in it. Just writing that a field called “Base Sale
Value” in a user input form needs to be filled in with “a numeric
figure corresponding to the base sales value of a product” is not
enough. A short example to say what a base sales value is, its
relationship to the price of a product, and how it can be used in
the sales process is easier to comprehend. It is this business usage
of the application that is often lacking in user documentation that
emerges from technical teams.
Good documentation takes time. To be able to put screen shots
in a manual or online help requires that the developers have the
screens ready. If documentation should follow development, there
is a chance that there will be a time crunch (not too many releases
are delayed due to inadequate documentation) and the quality will
suffer. So documentation writers usually create documents on the
basis of design or solution specification documents, and put place-
holder screens. This is also risky because the specifications docu-
ments may not be up to date.
Software documentation also must be more complete with regard
to context and, in cross-references, across the entire software
documentation. Just by saying that a “Vendor Type” field is man-
datory for a sales order to be entered in the system is not complete.
Not only should one specify what type of input it needs, but one
should also provide all possible values that are acceptable, with a
reasonable explanation for each.
Documentation is a “pull” activity. Many times it is observed that
technical writers create documents on the basis of their under-
