Writing A Software Technical Reference Manual (part 2)

Find out how to organize your technical manual so it's easy to read and understand.

Moving On

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!

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.

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

System Shock

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.

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

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

Remote Control

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.

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

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.

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

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

Improving Yourself

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?

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.

Sealed With A Kiss

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!

This article was first published on 06 Feb 2003.