In our previous legacy system modernization blog, we focused on the importance of understanding exactly what your legacy system does, and how it does it – before planning your route to modernization.
This seemingly obvious process, like the subject of this particular blog, is often not given the priority it deserves.
And that takes time, as well as increasing frustration and delay.
Today, we’re talking about documentation – and the importance of creating and maintaining both user and support documents. It does sound obvious, doesn’t it? And you’d think it would be done as a matter of course. But, as we’ll see, that can sometimes not be further from the truth.
Consider the software engineering tool, CA Gen, where we have specialist expertise. The whole idea was that, being model-based, the documentation effectively WAS the model. This was a fundamental principle of the IEF, the forerunner to CA Gen. In theory, any competent person, involved in any part of the life cycle – from analysis to implementation – should be able to pick up the model, and understand how it was encoded. However, there are a number of reasons why the reality differs from the theory.
- The theory still requires the developers to enter descriptions and annotations where necessary. Developers are, of course, not writers. They like to code, and the need to add those descriptions gets put on the back burner and ultimately become “forgotten”. After so long, it simply gets overlooked as the path of least resistance becomes a little more trampled.
- Development methods inevitably move on and the development tools lose their synergy with the method. For example, whereas CA Gen had full support for information engineering methods, it is less suited to support current trends like UML and analysis methods of writing user stories
- There are many people with an interest in the documentation who don’t necessarily have access to CA Gen or the skillset to find the relevant documentation within it.
The impact of all this is self-explanatory. As discussed in the previous blog, you find yourself looking at a legacy system, scratching your head as to where to start. Had there been a mindset that documentation was maintained (for both users and support staff), you’d have a much better idea of how to begin.
Tools like Jumar’s Model Analyser and Model Reporter can be used to automate the analysis of the ‘as is’ state of the applications, but having documentation to complement this means you can make even more educated decisions at the start of the process.
What, therefore, can be done?
The solution can be boiled down to a three-step iterative process, comprising improvement, extraction and monitoring:
- Improve the information that is within the model. Tool like Jumar’s BulkUpdate allows for descriptions and notes to be added quickly and efficiently, using Office tools. Other Jumar tools can be used to extract information from various different development tools and bring it together. For example, Jumar has experience linking different development tools (IBMs Rational, CA ERwin Data Modeler, etc) with CA Gen and vice versa, thus allowing for the full life cycle coverage once again.
- Extract as much as possible from the models. Automation tools like Jumar’s Model Reporter and Model Analyser greatly help here. The first allows for automatic generation of User and support documents in different formats. The latter extracts all important model information to a local database where it can be queried easily. It also allows for complexity reporting so that you know where the focus of the documentation should be. It can also help in terms extracting certain business rules and problematic code constructs.
- Monitor for quality purposes. Once the documentation is up to date, ensure it is maintained by setting up appropriate QA processes. Again, tooling can help to carry out QA activities. Especially important when supporting a system which is only updated every so often or when quick production fixes are applied.
A word of caution though; using Model Analyser and Model Reporter can be a ‘quick fix’ – but it’ll be much more cost effective for your organisation if they are used as the starting point for a concerted, on-going plan to improve documentation.
While we’ve touched on CA Gen as an example here, this is true for practically any legacy system, but is a warning that we see repeatedly going unheeded.
In a recent client assignment we undertook here at Jumar, one of our experienced legacy experts took six weeks to complete the documentation of a system which should have been done by its previous custodians. Six weeks may sound like a long time, but it was dramatically accelerated by the use of automated analysis tools – and this investment in time ensures that any future development within that legacy system can take place at a fraction of the time and cost than it would have done without those robust documents.
So, what is our advice to alleviate the problems caused by a lack of documentation? Quite simply, you can AUTOMATE your understanding of the system. By ‘automate’, we do genuinely mean that the process is not a manual one. There is an understandable suspicion towards claims of automation – with many thinking that there’s a low-cost development shop somewhere carrying out intensive tasks which vendors claim to automate. But the tools described here (and others within Jumar’s Project Phoenix suite of software) ARE genuinely automated – and we can demonstrate this. This will form the basis of next month’s blog – but for now, we hope this latest post shows the importance of documentation, and why now could be the time to grasp the nettle and get on top of the issue in your organisation.
We can help make it cheaper, faster and less stressful – just get in touch to find out exactly how.