It might be the last thing you want to read, but not having a well documented IT infrastructure (servers and networks) can lead to surprising events like critical systems running on unsupported servers.

Documentation must not only be accurate at the time it was created it should also meet these additional criteria:

• Available The people who need the information must be able to get at it.
• Editable Any documentation in the IT industry is quickly out of date, so it is essential that information is able to be correctly updated as soon as a change is required. Ideally the client or end-user should be able to do this, rather than waiting on the 'approved editor'.
• Current 'Out of date' is just a nice way of saying 'wrong'. The date on which the underlying information was updated should be shown on any reports either printed or viewed online.

In some cases it is effective for documentation to be generated from specific database driven applications and presented on a web site.

You care more about documentation after you've had to deal with the consequences of not having it.

Network Documentation

But I have a network diagram - see, isn't it nice…

Local and Wide area network documentation is frequently contained in pretty diagrams maintained in a general purpose graphics package such as Visio or something similar. Unfortunately such documentation also tends to be both out of date, and missing important information.

The problem isn't Visio (or whatever you do use), the problem is that an image is not a very good model for technical information.

A good network diagram is a thing of beauty and can provide an easily grasped overview of a distributed installation. But it's not enough. To be easily used, an image needs to fit on one page, which generally means A4 or at most A3. If you happen to have an A0 printer available good luck to you.

Behind the image

I'm not suggesting that you do away with your network diagram, in fact I think such a diagram is an important part of network documentation. It usually just isn't enough.

Network documentation should include at least:

• All your physical sites with addresses and contact details.
• Network numbering schemes (IP addresses), including gateways and name servers.
• Wide area connections, service numbers and speeds.
• Details of all fixed IP address devices and what they do. This means all your servers and printers.
• Firewall documentation. You probably have a firewall but do you know what it's letting through and why?
• Publicly visible services, such as email and web servers in your DMZ (you do separate your public servers from your live network don't you...)

And there's more; the point here is that a diagram or two isn't the right medium in which to either present or maintain this information.

So what's the answer?

Consider a structured information store (ie a database) where the details you need can be stored in a single location and updated as soon as the information changes. If you need printed documentation (and you will), predefined or ad hoc reports can select those items that are necessary. If the system is a bit flexible, you may even be able to automatically include that really nice diagram as well.

Application Documentation

Application documentation is required for any systems used within an organisation. Although this section describes documentation in terms of computer based applications it also applies to manual processes.

Program documentation

Program documentation is what the programmers see and use to modify or extend an application.

There are many approaches to program documentation. In my opinion, effective program documentation should be part embedded in the program code and maintained using the development environment. If programmers have to leave the development environment in order to create documentation it either wont get done at all or will be inadequate. Documentation that is part of the program is available in context when required and (depending on the programming language) may be extracted into isolated summaries when required.

Functional documentation

Functional documentation describes the fields, actions, reports etc available from a system. Think 'reference manual'.

Functional documentation can be suitable for online delivery either as help files or intranet pages. An important point here is consistency of expression - just because you know that 'click Ok', 'submit the form' and 'hit <enter>' will have the same effect doesn't mean that your readers will. You should expect the end users to be good at their jobs, not good at yours.

Functional documentation should be written, or at least reviewed, by someone with a deep understanding of the system. Otherwise you get pointless field documentation like 'Reference number: This field contains the reference number', which not nearly as useful as you might like.

Training documentation

Training documentation explains how to use the system and why you might make certain choices.

Training documentation is critically different from functional documentation. Training materials will typically omit many of the more obscure sections of a system while concentrating on the parts that everyone uses all the time. Training materials give more explanation about the choices available, why you might choose each one and the impacts of that decision. Training materials are often expressed in terms of the business task that the user is trying to achieve rather than the menu structures and flows of the application.

Business Process Documentation

This is a whole other bucket of worms. Really important - in fact important enough to warrant a separate spiel.