Writing a Software Technical Reference Manual (part 1) - Hard Decisions (
Page 4 of 5 )
The scope of this manual will largely depend on the nature of the
application. While the common goal remains to help install and maintain
the application, the nature and extent of information to be provided
will differ. For example, a software application like an e-mail client
add-on or Web-based intranet application would contain detailed
information on software architecture, internal components and APIs. On
the other hand, hardware like a keyboard or a network card would also
require detailed documentation on compatible/supported hardware and
software, together with information on configuration and physical
installation processes.
Another factor that will affect your scope is the extent to which your
manual needs to cater to other developers. If further development of
your application is definitely on the cards, information like the
application file structure, the variables used, extensibility of the
source code, and even some choice code segments will be a part of the
main document. Explaining how the application was developed and the
standards followed may, in fact, even be the overriding aspect in the
explanation of the software and its components.
Defining the scope of your manual is a non-trivial task, and requires
clear understanding of its audience, together with their level of
knowledge. It makes very little sense, for example, to write a manual
explaining the design and internals of the application's APIs when the
target customer is actually an administrator who's more interested in
reading about how to diagnose and troubleshoot problems. A clear profile
of the target audience, therefore, plays an important role in deciding
how successful your efforts in building this manual will be.
In order to develop this profile (and, therefore, target the manual
appropriately), you should make it a point to find out the customer's
goals in demanding such a manual. Some customers require the manual for
more efficient internal deployemnt of the software; in this case, more
stress should be laid on the configuration and tuning sections of the
manual. Other customers may ask for this manual so that they may provide
other software vendors, or technical partners, with sufficient technical
information on the software to build on it further; in this case, a
detailed discussion of APIs, control flow and architecture extensibility
would be appropriate.
When defining the scope, it is also important to give some thought to
how your manual will keep pace with changes in the software as it
evolves. A decision involved here is whether for any upgrades delivered,
a revised STRM will be delivered as well (the alternative here might be
to deliver an appendix capturing the changes in the application from the
previous release). Whatever your decision, it should be clearly
indicated within the introductory sections of the document, with
appropriate version numbers in the first case, and references to the
relevant sections in the second.
/ 11 
