I work on a couple of Web applications that are replacing legacy systems. But we’re not talking about a quick switcheroo here. Due to the processes that they accommodate and the amount of data they deal with, the systems we’re bumping out are complex enough that we’re having to phase them out.

This has the potential of turning into Science Horror Theater 5000 for the technical communicator (okay, so I could mention the DBAs and others, but this is mainly a tech comm blog). Not only do you have to document the new system, but you’re trying to educate users who have been doing things a certain way for years. You’ve got to tell them how to take a task they used to do and accomplish it the new way. No clean slate for you.

What can you do to alleviate the pain?

Talk to the customer and other project leadership about just how much time you ought to spend learning and documenting old processes or old tasks. You should consider the following factors.

I: Technical Support and Documentation for the Legacy System

How strong is tech support for the legacy system? If your organization has tech support in place, they should be informed of the cutover process and be ready to assist users in the transition. The more they can do, the less you have to.

If the legacy system has its own documentation, you can point the users to it, and you may be able to leverage some of the content. You can use the existing documentation as a guide for understanding the tasks that the users typically undertake.

II: Room in the Money Bin

Another factor is the funds available to the project. Your first priority is going to be producing documentation that will go forward, not documentation that will become unnecessary within a matter of months. If something has to give, it’s the documentation about the transition.

III: Amount of Bridging Code

How much will the new and legacy systems be bridged so that data are shared during the transition process? If there is bridging code in place, you may need to document where those connecting points are. Users need to know when dual data entry is needed and when they can use one system instead of another for certain tasks.

IV: Length of the Transition Process

The longer the transition process, the more releases there are likely to be. This means that users need release notes to explain what has changed in their processes since the last release. They need to know when to stop using the legacy system for particular tasks. The more releases you have, the more documentation you will need to provide. By the same token, the longer the transition period, the more time you have and the more documentation you will be able to create.

Conclusion

One of the projects I mentioned has had a lengthy transition period, and I have included documentation that explains the data bridging and explains where some dual data entry needs to occur. When we drop the last shovelful of dirt on the legacy system, I’ll have to remove all references to it in the documentation.

In the other project, the team agreed that because less bridging was taking place, we could leave out the transition documentation except in release instructions. The only bridging we do is converting data from the old database to the new one, and the transition period includes a period of dual data entry in some areas of the systems.

Of course, the second situation is the easiest. But if the transition isn’t going to be so straightforward, you can still make your job more manageable by setting clear limits on how much documentation about the transition itself is possible.