Writing A Software Technical Reference Manual (part 2) - Starting Off Easy (
Page 2 of 6 )
Having defined the scope of your manual, the next step is to build the
table of contents. While this can change from application to
application, the following heads of information would be the bare
minimum required:
1. Overview
This section provides introductory reading for your target audience,
explaining the purpose and scope of your manual.
1.1. Scope of the document
Define the kind of information that is covered/not covered by the
document
- for example, installation, administration, troubleshooting et al. For
information not covered in the document, include references to external
sources that will address the deficiencies.
1.2. Glossary
List and define terms and acronyms used in the document.
1.3. Conventions Used
Define conventions used for diagrams, code, output and text.
2. Introduction of Application
The idea in this section is to introduce the environment of the
application
- both the environment in which it was developed, and the environment
required for its installation and use.
2.1. Purpose
A brief introduction of the application's functions and raison d'etre.
2.2. Platform
Provide information on the platform used when designing the software.
This would include information on the IDE or programming language used,
the programming tools and ancillary utilities needed, and hardware
configurations (if any).
2.3. Compatibility
List the supported operating systems along with the file formats
required for installation on them.
2.4. Installation packages
Explain the packaging of the installation files, especially with respect
to the different operating systems, and provide instructions on
unpackaging and installing. Also, discuss the software initialization
process - list the variables that need to be configured and provide
instructions on how to accomplish this. For each configuration, explain
the possible settings and their impact, and also provide a recommended
setting.
In case your application includes certain optional/additional components
that the customer may choose not to install, explain the issues
involved, and provide a brief discussion of the pros and cons of each
alternative so as to help the customer make an informed decision.
If you're delivering software source code and you anticipate further
development of the software by external developers, discuss the
procedure for building new versions of the package from the source code
(depending on its relevance to your application and who you're writing
this manual for, you could also include this in the appendix).
