Post-documentation of a legacy application in industry

The challenge

The replacement of legacy systems is a major challenge for many companies. The functionalities that have been developed for these systems in the last few decades must generally be retained, but the aim is to switch to modern and future-proof technology. In many cases it is not even known which functionality is actually available and how the software works technically. Reasons for this can be that the developers have not been active in the company for a long time or that the software is poorly or not at all documented. This article presents an approach for the technical and functional post-documentation of a legacy application.

The solution

In the first step, the existing documents are analyzed and processed with Sysparency in order to obtain an initial assessment of the system. The system is then examined using a tool-based static code analysis in order to better assess the scope and the core elements of the system. Furthermore, manual code analysis is used as a supplement or extension if the tool-based code analysis alone cannot identify the relevant details or priorities. In the case of particularly complex functionalities, tool support is completely dispensed with and analyzed and documented purely manually. The entry points for the individual core functionalities must be identified and defined jointly in expert workshops. In addition, the following will be discussed at the expert workshops:

Overall architecture and division of the core functionalities into detailed documents

  • Priorities of program parts, methods and algorithms
  • Abstraction level of the documentation with regard to possible addressees
  • To ensure quality, a review takes place after each iteration.

 

Different documentation styles were used depending on the program part and complexity. Most of the documentation consists of 1) manual step-by-step documentation, 2) code snippets, 3) flow charts and 4) pseudocode.

  1. In manual step-by-step documentation, the source code is analyzed in detail (line by line) and technically relevant lines of code are included in the documentation. Lines that are only relevant for program execution are not taken into account. Complex functions are analyzed down to a defined level of detail (e.g. 3 levels). Auxiliary functions, general functions or functions specific to the programming language are omitted because they are not relevant for the documentation from a technical point of view. Lines that are ultimately taken into account are described in text form.
  2. In contrast to 1), code blocks can be combined and described textually as a whole. This makes sense, for example, to describe algorithms. The description of the individual lines would make little sense here. Code snippets are also useful for future developers in order to understand certain program blocks.
  3. Entire use cases or processes are represented by flowcharts on a higher level than 1) or 2). A flow chart provides an overview of which steps are carried out in which order in a particular use case or module.
  4. If certain functions or code blocks are very complicated or extensive, it makes sense to translate the entire block into pseudocode. Pseudocode is programming language independent and easier to read. Loops and branches are also mapped in the pseudocode.

 

In addition to the technical documentation, technical and architectural documentation must also be carried out. The entire system is analyzed as a whole and divided into components. Typical components are:

    • Front end or clients
    • Business logic
    • Server functionality
    • Database and access logic
      1.  
      1.