Writing by Peter Hilton

Where to start documenting a legacy system

What new team members need, to understand a system 2016-09-30 #documentation

Over on the Write the Docs Forum, a recent question asks how to get started with documenting a legacy system.

This situation tends to change how a programmer thinks about software documentation. When you build a system from scratch - greenfield development - you won’t necessarily notice if you don’t have enough documentation, or even none at all. The experience of starting to lead a team that has responsibility for maintaining a poorly-documented legacy system changes that. This situation leads to the discovery that the only thing harder than documenting software is trying to document legacy software built by people who have disappeared or who (claim to) have forgotten everything about it.

In general, I suggest two things in parallel for this kind of system documentation: a brief system overview and one kind of detailed documentation.

System overview

By system overview I mean something short that introduces the different perspectives on the system. Specifically, I mean max one ‘page’ each on the following as you can figure out.

The trick with each of these is to provide a starting point for a developer to delve deeper by asking other people or reading the source code. You typically won’t need a lot of detail in every area. However, you will probably need at least some more detailed documentation.

Detailed documentation

However, each system usually has one area that features enough complexity to require more detailed documentation. Some systems have complex data, or data models that use obscure domain jargon. Other systems appear simple but support a complex business process. In some systems, the complexity lies in complex user-interaction and obscure user interface details.

By the time you have compiled a few pages of system overview, you will probably have figured out which kind of complexity characterises the system. Next, add more detailed documentation that explains the system’s most complex aspect.

Your mileage may vary, but my experience of internal business systems suggests that a data dictionary provides the most value on account, because what things mean is the only thing that you can’t figure out by studying the source code.

Next steps

Once you have basic system documentation, impossible things such as fixing bugs should become possible. The next steps are to help people do things more quickly. I recommend focusing on what everyone has in common, whatever they do later: getting started.

In all of the above, focus on identifying the audience for each piece of documentation, and identifying and understanding your current biggest problem.

Share on TwitterShare on LinkedIn