Starting Off Easy - Practices

With the groundwork out of the way, this concluding partexamines the standard components of a technical reference manual,explaining what goes into each section and why. It also discusses theprocess by which such a manual should be reviewed and vetted prior todelivery to a customer.

TABLE OF CONTENTS:

By: Deepa L, (c) Melonfire

Poor Best

Rating:

/ 3

February 13, 2003

print this article

SEARCH DEV SHED

TOOLS YOU CAN USE

Having defined the scope of your manual, the next step is to build thetable of contents. While this can change from application toapplication, the following heads of information would be the bareminimum 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 thedocument- for example, installation, administration, troubleshooting et al. Forinformation not covered in the document, include references to externalsources 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 theapplication- both the environment in which it was developed, and the environmentrequired 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 hardwareconfigurations (if any).

2.3. Compatibility
List the supported operating systems along with the file formatsrequired for installation on them.

2.4. Installation packages
Explain the packaging of the installation files, especially with respectto the different operating systems, and provide instructions onunpackaging and installing. Also, discuss the software initializationprocess - list the variables that need to be configured and provideinstructions on how to accomplish this. For each configuration, explainthe possible settings and their impact, and also provide a recommendedsetting.

In case your application includes certain optional/additional componentsthat the customer may choose not to install, explain the issuesinvolved, and provide a brief discussion of the pros and cons of eachalternative so as to help the customer make an informed decision.

If you're delivering software source code and you anticipate furtherdevelopment of the software by external developers, discuss theprocedure for building new versions of the package from the source code(depending on its relevance to your application and who you're writingthis manual for, you could also include this in the appendix).

Next: System Shock >>