Logo         Community
The Company
Your Account
Contact Us
Writing A Software Technical Reference Manual (part 2)
Find out how to organize your technical manual so it's easy to read and understand.

| Starting Off Easy |

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

How to do Everything with PHP & MySQL
How to do Everything with PHP & MySQL, the best-selling book by Melonfire, explains how to take full advantage of PHP's built-in support for MySQL and link the results of database queries to Web pages. You'll get full details on PHP programming and MySQL database development, and then you'll learn to use these two cutting-edge technologies together. Easy-to-follow sample applications include a PHP online shopping cart, a MySQL order tracking system, and a PHP/MySQL news publishing system.

Read more, or grab your copy now!

previous page more like this  print this article  next page
In trog...
Logging With PHP
Building A Quick-And-Dirty PHP/MySQL Publishing System
Output Buffering With PHP
Date/Time Processing With PHP
Creating Web Calendars With The PEAR Calendar Class
In the hitg report...
Crime Scenes
Animal Attraction
Lord Of The Strings
In boombox...
Patience - George Michael
Think Tank - Blur
My Private Nation - Train
In colophon...
Hostage - Robert Crais
The Dead Heart - Douglas Kennedy
Right As Rain - George Pelecanos
In cut!...
American Chai
The Core
Find out how you can use this article on your own Web site!

Copyright © 1998-2018 Melonfire. All rights reserved
Terms and Conditions | Feedback