Home arrow Practices arrow Page 2 - Writing A Software Technical Reference Manual (part 2)

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.

  1. Writing A Software Technical Reference Manual (part 2)
  2. Starting Off Easy
  3. System Shock
  4. Remote Control
  5. Improving Yourself
  6. Sealed With A Kiss
By: Deepa L, (c) Melonfire
Rating: starstarstarstarstar / 3
February 13, 2003

print this article


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).

>>> More Practices Articles          >>> More By Deepa L, (c) Melonfire

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: