Wise Words - Technical Author, Technical Writer

Some hints on documenting code that won't make your developers complain about the work load, but may save an enormous amount of time in a few years.

A lot of my work has involved the "reverse engineering" of systems in order to document the functionality and the technical details of the implementation. This was needed because the original developers had done no documentation, or only fragments, and had either left the company or moved on to other things.

The result of earlier neglect of documentation was that when a substantial revision was needed, or responsibility for the system changed hands, a detailed analysis of the system had to be carried out. As a technical author, I have pieced together the fragments of documentation, interviewed those with some knowledge of the system and gone through the code in order to document the system to the required level. The first step is usually to produce a thorough description of the functionality of the system - it is surprising how many production systems lack an adequate functional specification!

This problem is particularly acute in the e-commerce field, because of the pressure to deliver in a short time, and the impatience of young software developers who want to get on with coding and see results. But this business also has high staff turnover and needs regular upgrades of its technology.

This article is to describe what I consider a bare-bones approach to documentation. It's based on what I myself would have found most useful and time-saving had it been available on a documentation project. I am giving something away here - taking my advice would reduce the amount of work available for me! However, I recommend the involvement of a technical author right from the start whenever feasible, even if not full-time.

A proper functional specification costs time and money now, but saves much more time and money later. Unless you intend to throw the lot away and start all over again, something like it will be done some day.

I am very reluctant to suggest short cuts here, because so many systems include traps for the user that were not spotted before the system went live. But if the system is properly modular, developers can start work on coding one part while the functional specs for other parts are still incomplete.

Always start from the business processes involved. Map out the users' most likely paths through the system. Make these the easiest and most obvious ways to go.

The functional spec should be kept up to date as the requirements are reviewed and updates are made, so that the document is always an accurate description of the functionality of the site. It then serves as an introduction to and overview of the site for the benefit of new staff and of management.

If your system needs user documentation, this should be begun while the specification is still being written, not left till the last moment.

There is a problem in documentation of duplication of information. If you have several documents covering the same information, they must all be written and kept up to date. The work-load this creates can be a deterrent to keeping proper documentation in the first place.

In particular, functional specs and user manuals contain much the same information, but have to be written and presented very differently. I wish to emphasise that user manuals should be written for the user, and I do not believe you should compromise on that. However, if you are short on time and labour, here is a compromise that can work. (I have not had an opportunity to put it into practce, though.)

Write a functional specification, with the usual rigour, but phrase it in terms of instructions to the user. This document will serve as part of the functional specification but, when finished, can be edited into a user manual. What's more, you will have ensured that all requirements will have been viewed from the user's point of view - always a good thing.

Where there is a functional requirement that is not relevant to the user, place it in a separate appendix, cross-referenced to the draft user manual.
The two documents together, the user manual and the appendix, become your official functional spec. If you try this, please let me know how you get on.

It's worth considering documenting your internal standards, change control and do on, especially if you have high staff turnover.

Technical documentation

Technical documentation is hardly needed if code is commented properly. The documentation then boils down to a single document containing general information, for example, catalogues or maps of software assets, entity-relationship diagrams, directory structure maps and similar, which can often be generated automatically by your development software. If the system is a Web site, a site map is desirable - there is now software for automatic generation of these.

The most important thing is well-commented code, and that is most easily and reliably done at the time by the developer concerned. It should be done systematically, but briefly, and need not take more than minutes to do.

I suggest the following approach. This should be done at both of the following levels:

Program, module or class
Procedure or method

Summary of purpose of the program or procedure. This should be what it does in the immediate context of the program, the reason why it would be called.
Inputs: A description of the input parameters to the procedure, and any other inputs (e.g., a file that is read).
Any changes made to the database.
A description of the result returned to the calling program, if any, and any other outputs (e.g., a file that is written).
A summary of the reason for choosing the design or implementation over any other that may have been considered, where applicable.

In many cases, these may not all have to be filled in. Where they do, a few lines are likely to suffice in most cases.

In addition, where not covered by the rules above, there should be a short description of all objects that are used in a system, at the top level to which the object is local.

The exception to the above is that commenting code (HTML, Javascript and so on) to be downloaded to a browser wastes users' share of bandwidth. In this case, comments should be included in the single document containing general information, referred to above.

So, following the above advice, a procedure may include something like the following:

Input: an invoice number

               Updates: INVOICES directly and CUSTOMERS by
              calling update_customer

               Returns: true if it completes correctly, false
              otherwise

               Comments: This updates CUSTOMERS indirectly
              because <reason here>

Handy hints on technical documentation