Devshed 08/14/2004 09:18:56 AM

Computer Programming
Writing A Software Technical Reference Manual (part 2)
Contributed by Deepa L, (c) Melonfire
2003−02−13
[ Send Me Similar Content When Posted ]
[ Add Developer Shed Headlines To Your Site ]

DISCUSS NEWS SEND PRINT PDF

Article Index: In the first part of this article, I discussed the purpose and goals of a software technical
reference manual, explaining who the target audience usually is and how to cater to its needs.
I also talked a little bit about how to go about deciding the scope of things to be covered in
your manual, and discussed the standard components of a stylesheet for such a manual.

In this second article, I'll build on what you've learned thus far by putting together a sample
table of contents for this type of manual, and discussing how to break the technical material
up into a format that is both structured and easily understandable. Keep reading! 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

1/7
Devshed 08/14/2004 09:18:56 AM

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). Once you've got the
introductory material out of the way, it's time to delve into the nitty−gritty of system and
component design and function.

3. System
This is the meat of the document. The idea here is to first present an overview of the system
and then move on to each component and its function. This section as a whole needs to cover
the explanation of the way your application is structured and how the various pieces of it
work together.

3.1. System Overview

In this section, start with high−level architectural diagrams of the system design, together
with descriptions of the components used and their relationships via a modeling language
(UML is good for this). Also include a description of the various modules that make up the
system.

Going deeper, address all "global" aspects of the application. List and describe the global
configuration and runtime variables defined within the system. Detailed information on
where and how these variables are stored can be included in an appendix.

Address your data storage next. Define the data structures used by the system for system,
configuration and user data and discuss the format of their storage containers (whether they

2/7
Devshed 08/14/2004 09:18:56 AM
are databases, flat files or some other format). Provide a brief explanation of the
requirements that resulted in the choice of a particular format, and address the resultant
constraints or benefits. The exact directory structure with file names and instructions on how
to back this data up before upgrading or re−installing can be included in an appendix.

Next, explain the security and performance considerations. Describe the user levels defined
in the application, their access permissions and the techniques used by you to ensure data
protection. Also talk about the performance enhancing techniques incorporated, their effects
and their constraints − for example, caching and platform−specific tuning options. You may
choose to relegate the details like the cache size, location, backup considerations and
customizing options to an appendix.

3.2. Component Overview

Drilling deeper into the application components, this section should explain the purpose of
each component, its functions, its data input and output formats, its input and output
interfaces, its internal business logic, and its interaction with other components. You can
include pseudo−code wherever needed to ensure that the details are clearly communicated.

On the whole, this section will be similar in structure to the system overview except that you
will be describing a component instead of the system.

Your heads of information could be:

* Scope of functions
Talk briefly about what the component does and the requirement it fulfills.

* Block diagram
This diagram should highlight the structure of the component, displaying the
sub−components, if any, and the local APIs. You may choose not to have this block diagram
if the component is a single unit without any further sub−components.

* Control flow diagram

This diagram should depict the flow within the component for execution of its function(s).
Highlight the input and output paths, the events that trigger the component APIs, and the
points at which this component interacts with other components.

Explain the flow depicted in the diagram in detail − describe the input/output instances and
describe the data formats, the events that trigger the local/private APIs and the events that
trigger interaction with other components (you can describe the local APIs in detail in the
next section). Similarly, while talking about the interaction with other components, introduce
the system interfaces (public APIs) called, and reference detailed notes in other sections of
the document.

* Component APIs
Having introduced the component APIs, describe them here. For each API, include
information on its access method (socket, local function call, remote function call and so on),
the arguments to be provided, boundary conditions and return values.

* Configuration and run time variables

List the variables relevant to the component, with a brief description of each, allowed values
or value range and data type.

3/7
Devshed 08/14/2004 09:18:56 AM

* Data Structure
Since you have already defined the system−wide data structures, talk about other data
structures used by the component, if any.

* Sub−components
If sub−components exist, list them here and, for each, briefly describe all the above heads of
information.

* Exception handling and error types

Discuss the errors you have anticipated and how your exception handler will deal with them.
Also define the error types you have identified.

Commonly, the error types are based on severity of the problem − notification, warning, or
fatal error are the three most common − and they are depicted differently to help the user
identify them. For example, error types may be color coded within the application for easy
identification − talk about these conventions and what each one signifies too.

* Diagnostics
Finally, talk about the logs and reports generated by this component. Discuss the method of
accessing these logs, filters available to sift through them, and the formats in which they are
generated. You could provide samples and discuss detailed log analysis or troubleshooting in
an appendix.

3.3. System APIs

Talk about the interfaces between components here (public APIs). Since you will have
introduced most of these APIs while describing the flow of the components, this section
could simply be information on their access methods, boundary conditions, arguments
needed and return values.

3.4. System Interfaces

This section will address any interfacing that the system needs to do with other existing
systems in the customer's office. For example, if your application is to automate the
generation of employee salary/bonus statements, it would possibly interface with the
accounting system to extract the salary info for the salesmen, and with the sales system to
calculate sales per person and corresponding commission/bonus payable. In such cases,
describe the instances of data extraction/insertion, data formats, the necessary configurations
and back−up considerations for each interface. Once the business logic of the application is
done with, it's time to discuss what the user actually sees − the user interface − together with
administration issues and processes.

4. User Interface
This section will touch upon the user interface of your application. Information to be
highlighted here would be the platform on which the interface has been developed, the
browsers supported (in case of a Web application) and the display settings required.

An explanation of how the interface has been coded, and instructions for
customizing/duplicating those pages should also be included here. For example, if you have
used templates to develop your interface and separate the business logic from the interface,
you would need to explain the sub−division of the interface as various templates, local and
global variables, the API used to connect the templates with the content.

4/7
Devshed 08/14/2004 09:18:56 AM

While you could use this section to describe/give examples of each of the above aspects, the
appendix must contain a detailed list of the local and global variables defined, the template
files and their locations, and the program files and their location. Provide well−commented
code samples to clarify things as needed.

5. Administration/Control
In this section, list the various methods of accessing administrative tools. For each method,
list the options (Web interface or console). For each of these options, you could further
explain the format/protocol expected, available functions and default and recommended
settings.

6. Appendices
For each section of the TOC, abstract out chunks of information that would distract from the
main purpose of discussion, but which are relevant nevertheless. These items can be
discussed in detail in the appendices. The following are some recommendations:

* Manual backup/restore procedures In case your application does not provide for backup
and restoration of user data, you would need to provide instructions on the manual process to
accomplish this. Including a list of the data storage containers used, their formats and sizes,
and recommended usage capacity would be helpful as well.

* Data structures
For all the data structures used in the system, provide detailed information on the data
storage containers, their formats and allowed data types, and sizes or maximum capacities.

* Interface elements
List all the variables and files related to the user interface, together with diagrams or screen
flow charts explaining how the various screens are built and connected to each other.

* Coding standards
Discuss the conventions followed while coding − block indentation, script header and footer
blocks, script revision logs, and comments for variable and function definitions. Also
describe the format, style and length of function names, variable names, file names, and
database and table names.

* Installation packages
Instructions on how to (re)build or compile the software from source code.

* Logs and reports

Samples of logs and reports along with a discussion on how they may be analyzed. If your
applications includes tools or filters to assist in this process, a discussion of how these tools
may be used, together with sample scenarios.

* References
Mention the other documents delivered with the application, with a brief discussion of what
each one covers and their version numbers.

* Development history
A development history of the application is also useful, especially for applications that are
constantly under development. The best way to go about this is to show a timeline of the

5/7
Devshed 08/14/2004 09:18:56 AM
various versions, together with a list of the important features added at each stage. For
example, if your application uses the "xx.yy" system of version numbering (with "xx" being
incremented for baseline changes and "yy" being incremented for intermediate releases), you
can provide a brief snapshot of the application at each baseline and intermediate release.
With the document done, you are ready for review. The review process of any technical
document has two aspects: the technical review and the editorial review.

In the technical review, the intention is to verify that all the information provided is correct.
This is by no means a trivial job, and the best way to go about it would be to provide a
checklist to the reviewer for each section. An example for the section on APIs would be:

1. Is the name of the API correct?

2. Are the access methods mentioned correct?

3. Are the boundary values all present and accounted for?

4. Are the arguments required all stated correctly?

5. Are the return values correct?

Such an enumeration not only ensures that the reviewer focuses on the important points, it
will also help him/her notice missing pieces of information.

The editorial review can also follow the same process. The important aspects to assess in an
editorial review are:

1. Is the grammar and spelling correct?

2. Is style usage consistent?

3. Is verbiage used consistently?

4. Is the tone of the document consistent (active versus passive voice, first person versus
third person)?

5. Is the flow of the document logical?

6. Are the headings indicative?

7. Is any paragraph too long?

8. Does a particular section address more than one issue? Should it really be split or
sub−divided further?

9. Is there too much or too little information on any aspect?

10. Is any particular point in the main document body that would be more suitable as an
appendix?

11. Should any portion of the appendices be in the main document body?

6/7
Devshed 08/14/2004 09:18:56 AM

Potential reviewers would be co−developers − ideally the people who developed the
requirements specification and the design document − as well as other developers or
managers who worked on the technical aspects of the project. A wise practice would be to
have more than one reviewer for each item and start incorporating feedback only when all
reviews are in.

Another consideration in the delivery of the manual is the version nomenclature. You could
tie this in with the application's "xx.yy" nomenclature, with "xx" changing with every
baseline change, and "yy" changing for every intermediate release of the manual. Also, when
you revise the document, do record a reason for, or description of, the change. With all of
this behind you, you will finally be ready to release the manual. The following frills will
complete the package:

1. Cover page

• The name of the software should be written in accordance with the brand decided.
• The version number of the software should be clearly stated.
• The name of the developer with address and contact numbers.

2. Table of contents
• The topics should be linked to the matter inside.

3. Notifications for proprietorship and confidentiality

4. Headers and footers

• Headers could include the project name and version number of the document.
• Footers can have the page numbers and a short confidentiality notice.

It might also be a good idea to include a feedback form as the last page, as your users will
probably get back to you with suggestions. This will be especially useful if there is a second
phase of development for the software.

And that's about it. Publish your manual (either on paper or as an electronic PDF) to your
customer, and relax − you've earned it!

Note: Examples are illustrative only, and are not meant for a production environment.
Melonfire provides no warranties or support for the source code described in this article.
YMMV!

7/7