Writing A Software Technical Reference Manual (part 1)

Writing code is easy. Explaining it is a whole new ball game.

Talking Geek

If you’ve been following this column regularly, you already know the basics of writing a user manual. It’s pretty simple - put yourself in the mind of the user, and try to answer his or her most frequently asked questions in a concise and effective manner.

This article, however, deals with a different beast, one that is not so easy to tame - the Software Technical Reference Manual (STRM). Written especially for developers, programmers, software architects and other assorted geeks, it’s usually filled with technical gobbledygook and complex diagrams illustrating the guts of a software application. It’s complicated, intimidating and usually fairly stressful to write…and they’d usually like it yesterday, please.

Over the next few pages, I’m going to offer you a few tips and techniques, culled from my own experiences, that might help in making the process of developing such a manual less painful. As you’ll see, proper planning and the right attitude can play an important role here, enabling you to both get your arms around the technical details and compile them into a usable, structured format that serves the needs of your customer.

Let’s get going!

Under The Microscope

As the name suggests, the Software Technical Reference Manual (STRM) is concerned solely with the technical aspects of a software application - how the application is structured, how each component works and how to install and configure it. The idea is to give the customer independence in installation, maintenance, administration and further development of the application.

From the developer’s point of view, the STRM is a blueprint of the application that allows him/her to continue development from the last release. The STRM provides developers with the knowledge needed to hit the ground running when extending or adding on to an application, providing them with the level of detail needed to quickly and rapidly make leveraged changes to an application’s code tree.

The audience, therefore, is technically knowledgeable in both cases - either the customer’s MIS department or developers who want to enhance, improve or modify the application.

Given the content and the audience, this document is usually a development team deliverable…unless you have a technical writer in the team with a very sound technical background. A very big advantage of this, especially as compared to support documentation like user manuals and help files, is that the time spent on information collection is negligible; almost all of it is already captured in the planning stages of the software, in the software requirements document and the software design document (read more about these at ).

With these two documents in hand and, given the fact that the person writing the STRM would have been an integral part of the development process already, actually producing this document becomes a matter of:

  1. Defining the scope of the manual

  2. Setting the conventions

  3. Developing the table of contents

  4. Production

  5. Review

In this article, I’ll be focusing on the first two steps, with a list of things you should keep in mind when formulating the structure and style of your manual.

A Little Knowledge…

Any developer attempting this document should ensure that (s)he has:

  • A sound understanding of how the project is structured

  • Complete knowledge of the control flow within and between all components

  • Complete knowledge of all the APIs in the application

  • Knowledge of the data structures and the storage containers used

  • Knowledge of the variables used in all the components

  • An understanding of how the installation files are packaged

  • An understanding of how the user interface has been developed

  • Knowledge of the variables that need to be configured to initialize the application

  • Sufficient knowledge of the software platform on which the application has been developed.

While the requirements specification and design documents usually contain this information too, an understanding of the reasons why, say, a particular API has a certain boundary value, or a certain variable is a configuration variable and not a runtime variable, would be invaluable to someone explaining their utility.

Assuming adequate knowledge on the part of the developer/writer, the next step is to assess the scope of the material covered by the STRM. Let’s look at that next.

Hard Decisions

The scope of this manual will largely depend on the nature of the application. While the common goal remains to help install and maintain the application, the nature and extent of information to be provided will differ. For example, a software application like an e-mail client add-on or Web-based intranet application would contain detailed information on software architecture, internal components and APIs. On the other hand, hardware like a keyboard or a network card would also require detailed documentation on compatible/supported hardware and software, together with information on configuration and physical installation processes.

Another factor that will affect your scope is the extent to which your manual needs to cater to other developers. If further development of your application is definitely on the cards, information like the application file structure, the variables used, extensibility of the source code, and even some choice code segments will be a part of the main document. Explaining how the application was developed and the standards followed may, in fact, even be the overriding aspect in the explanation of the software and its components.

Defining the scope of your manual is a non-trivial task, and requires clear understanding of its audience, together with their level of knowledge. It makes very little sense, for example, to write a manual explaining the design and internals of the application’s APIs when the target customer is actually an administrator who’s more interested in reading about how to diagnose and troubleshoot problems. A clear profile of the target audience, therefore, plays an important role in deciding how successful your efforts in building this manual will be.

In order to develop this profile (and, therefore, target the manual appropriately), you should make it a point to find out the customer’s goals in demanding such a manual. Some customers require the manual for more efficient internal deployemnt of the software; in this case, more stress should be laid on the configuration and tuning sections of the manual. Other customers may ask for this manual so that they may provide other software vendors, or technical partners, with sufficient technical information on the software to build on it further; in this case, a detailed discussion of APIs, control flow and architecture extensibility would be appropriate.

When defining the scope, it is also important to give some thought to how your manual will keep pace with changes in the software as it evolves. A decision involved here is whether for any upgrades delivered, a revised STRM will be delivered as well (the alternative here might be to deliver an appendix capturing the changes in the application from the previous release). Whatever your decision, it should be clearly indicated within the introductory sections of the document, with appropriate version numbers in the first case, and references to the relevant sections in the second.

Doing It In Style

Having defined the scope and target audience, you can move on to setting conventions for the document - the tone of language, the formatting of different levels of text, and so on. This will make filling in the meat (once you have the TOC) a much faster process. You need to decide on:

  • Headings: Headings are usually used to indicate the beginning of a particular segment of information - section heads, sub-section heads and so on. Decide on the levels of information that you want to have (it is usually not advisable to have more than 3) and set styles for them. Avoid stacking headings immediately one after the other. Structure your content so that there is some introductory text after a heading.

  • Styles: Your manual will present the users with at least four categories of text; the idea behind setting styles is to make it easier to differentiate between them:

  1. Instructional text

  2. Application output/code listings

  3. Screen/module/component labels

  4. Text that the user needs to input

Typically, code listings and input/output text are formatted using fixed-width fonts like Courier, while other text may be formatted in an easy-on-the-eyes typeface.

  • Indented text blocks: This is text that is peripheral to the point that you are making, either background information on a concept you’re introducing or a warning related to some functional step that you’re explaining. Indentation helps to separate it from the main body; add a little icon (like an exclamation or a question mark) to quickly help the reader identify the type of information contained within the indented block.

  • Tables: Tabulating data is a great way to present data in a snapshot. Set conventions for the look of the tables - bold, centered and title case text in the header row - as well as the manner of referencing each table.

A good idea for referencing is to have section-wise reference numbers - for example, the reference “Table 1-03” indicates table 3 in section 1. Each table should also have a caption describing the data contained in it.

  • Diagrams: Engineers love diagrams and flow charts - and an important part of your manual is going to be its diagrams. Decide in advance how you would like to depict the different elements in the diagram; for example, you could use arrows to indicate the direction of control flow and bubbles to indicate processes. These design elements should be used consistently throughout the manual.

Each diagrams should have a caption describing what it depicts and a reference number - again, it would be a good idea to tie this in with the section number.

  • Screenshots: Screenshots are used either to simply display how a screen looks, or to indicate its different elements. In the latter case, the callouts labeling the different screen elements will be a prominent part of the picture, and you should strive to make their arrangement uncluttered. Ideally, all callouts should be on the same side of the screenshot; however, this may not be always possible. The reference number and caption are a requirement here too.

  • Bullets and numbering: Bullets and numbering can also help to break up complex concepts into simpler, smaller information nuggets. The convention here is to use numbering for sequential information only (for example, steps to perform a task) and bullets for other related information that is best presented in points instead of a paragraph (for example, a list of configuration variables).

Bullets also allow you to group together points related to a concept and ascribe them levels of importance. Much care and consideration should be given to the grouping of information in this manner - it could easily be as confounding as useful.

  • Terminology: A very, very important rule of creating technical documentation is to be consistent in your use of words. For example, if you’re using the word “function” to indicate the, well, functions of your software, you shouldn’t at any point switch to “features”, “commands”, “menu items” or “actions”. To this end, make yourself a glossary of the terms that you’re going to use right at the start, and stick to them consistently.

At this point, you’re ready to actually begin work. Spend some time analyzing the structure and components of the application, get together with the developers to get your questions answered, and begin breaking up the manual conceptually into different sections.

I’ll assist you in this process in the next, and concluding, section of this article, when I’ll show the components of a standard table of contents for an STRM, and also discuss how to ensure accuracy of your material via technical and editorial review. Make sure you come back for that!

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 29 Jan 2003.