What to put in software maintenance documentation

There are a number of different approaches to standardising the developing maintenance documentation, neither of which actually works particularly well:

• Leave it to the developers: just tell the developers to document what they do, and hope that they do a good job. Given that most developers would rather cut some more code than write documentation, this is not generally a successful approach.
• Give them a standard set of headings to fill in for each module: "Introduction", "Glossary", "Tables accessed", "Tables altered", and so on. This is fine if you don't mind a lot of boilerplate: once a developer finds that they can get away with "Tables accessed: See code" they'll do it every time. Also, there is the assumption that every module is the same size and complexity and uses the same techniques (and therefore the same headings will do for all of them): this is seldom the case.

It's important to realise that documentation development is the same as code development in this sense: if you don't design it before you start work, you're going to run into trouble. And the more design you do, the less trouble you're going to run into.

This article is about an approach that we have been using for two decades to design documentation sets, both for software user documentation and maintenance documentation (and for other kinds of documentation as well). It's simple, logical, and is used by 99% of technical writers the world over.

The approach is "audience and task analysis", and it works like this:

• figure out who you're writing for ("audience")
• figure out what they're trying to do ("task")
• figure out what they already know about that task ("assumed knowledge")
• figure out what else they'll need to know
• write it down

It's almost as easy as it sounds, and it will give you a different answer for each development environment, and possibly each project, that you've worked on.

Here's a (purely fictional) case study: A large insurance company has a 10-year-old COBOL application which they hope to commercialise and sell. They are going to take the existing product and add a web front end to it progressively, using the underlying data and replacing each green-screen interface one at a time with Java. A separate team of developers will look after the Java part of the application. During this process, users will have to jump between a terminal emulator and a web browser, depending on what part of the system they're working on. When this rewrite is finished, the insurance company is going to license the code to a multinational software company who will then double-byte enable it, add some more functionality and sell it to insurance companies worldwide. Before all of this starts, they have decided to get the maintenance documentation for the product up to date; and in doing this they have found that the only maintenance documentation they have is 10 years out of date and not worth reusing. Your job is to come up with a maintenance documentation strategy.

First, let's identify the audiences. There are several:

• the existing development team
• the new Java development team
• the multinational's double-byte development team
• the multinational's maintenance team

Now let's look at each of the audiences in turn and work out what tasks they have to perform:

Existing development team

This team will have to maintain an ever-shrinking base of COBOL interface code, along with some underlying COBOL code which will remain in the application after the rewrite, until the multinational's rewrite is complete, at which point they will have to carry out a data migration to the multinational version of the product. In the meantime, there will be legislative changes (they happen every year in the insurance industry), and there will also be repairs to be made to the COBOL code, and they will have to identify the source of problems in the data (some of which will be generated from the existing COBOL code, and some from the new Java code). Summarising that as a set of tasks:

• repair COBOL code
• enhance COBOL code
• track down data problems
• do data migration

The new Java development team will have to:

• write Java replacement
• document what they've developed
• test the replacement

Now let's take a couple of these tasks and analyse them further:

Existing development team: repair COBOL code

What assumed knowledge can we take for granted from the existing maintenance team? Obviously, they're going to be expert COBOL programmers, and they're going to know about insurance. Let's make the simplifying assumption that they know how this particular application works, and that this knowledge (which they have in their heads, and walk out the door with each day) is going to continue to be available to the company. (That's not always the case: sometimes there are only four or five expert maintenance programmers - which isn't enough to ensure that all of them are going to survive (and be in the same job) till the end of the program. There is also the risk that they will walk out in a block and demand contractor rates plus bonuses!).

What else do they need to know in order to perform this particular task? They can fix the existing code, and they know what they're doing. But remember that when they make a repair, they'll have to pass that knowledge on to other parts of the project. So the knowledge that they'll need will be:

• use the change management system

New Java development team: write Java replacement

Let's assume that the new Java development team have come out of some other part of the same insurance company, so they understand insurance. Let's also assume that they know Java, and the other technologies they'll need in order to get at the data.

Before they write a replacement for part of the COBOL UI (user interface), they'll need to know:

• what the old UI does, including all of the validation rules
• what data it interfaces to
• what the underlying structure of the data is (so that they can optimise the access, rather than blindly follow what's in the old code)

They'll also need a set of UI design rules, coding rules, and some procedures on change management.

Summarising this, the knowledge they'll need will be:

• validation rules of each screen
• data accessed by each screen, and relationship between fields and data
• data dictionary, including business context of each element
• E-R diagrams
• UI design rules
• Java coding rules
• how to use the change management system

Summary

There are a number of key points in this article:

• even though it was developed for user documentation analysis, audience and task analysis can be applied to maintenance documentation
• each development is unique, and needs its own analysis
• no matter how complex it is, you can break down a documentation problem into manageable pieces by using audience and task analysis

We have been using this tool for many years, so if you need help with some aspect of it, please give us a call.

This article may be reproduced only with the permission of HCi (email HCi ). Copyright HCi, 2001-2.