How to document attributes from legacy application

Question

I have to replace an old application (Database, C++ UI) which is mainly for data administration, with on a new application (Same Database, Spring-Boot, Angular).

We want to document how the application (the old and the new) handles every attribute. That is:

• Name of the attribute
• Type of the attribute
• Location in UI
• Location in Database
• Editable
• Optional / Must
• ...some more meta..

I see some big problems with this task. As

• The documention is never complete
• The documention is redundant and gets old/wrong
• It is a lot of work (software archiology)

Could someone please give me advice for my questions:

• Which format or kind of tool should I use (no specific tool recommendation expected, I know this would be off-topic here)?
• When to start or stop documenting?
• How can I prevent the documentation getting outdated?

If anybody has experience with this kind of task I would very much appreciate any advice. Thanks

Answer 1

A complete documentation of your database model makes a lot of sense regardless whether one is going to rewrite this application or not. It will not just be helpful for replacing the old application, but also help to keep the old application maintainable.

So if there is currently no documentation process for the data model in place, I would start by establishing one. This process should be not defined as part of the replacement project, but also as part of the maintenance process of the existing application (as well as for the upcoming new application).

In case this is a relational database, just use one of the documentation tools for ER models, there are several ones available at the market, free tools as well as commercial, and UML tools can be used for this, too. Just pick one which fits best to your current environment, team's knowledge and budget.

This solves most of the documentation requirements mentioned in the question, except for the "location in UI" part and the "editable" parts. You can document parts of this also in the ER model docs, but I would recommend not to focus so much at the exact location, but more on the intented usage of the attribute (maybe inside an UI), mostly agnostic from the specific UI. That makes sure the documentation does not lose its validity when the new application version will go into production.

So in short

When to start or stop documenting? How can I prevent the documentation getting outdated?

Start now and never stop again, make sure each change to the datamodel is documented immediately. Having your datamodel not documented is a horrible sitation, a huge technical debt which will always backfire to you, regardless if you are do a rewrite, refactoring or ordinary maintenance.