Development of technical documentation for the existing software

Description

On this small project, our client was a global media company that produces and distributes print, digital, and video content of the world’s leading brands. The company had two obsolete software products written in Delphi 7:

workflow automation software (analytics, billing, etc.)
software for automation and management of ad sales and ABS (advertising booking system) with CRM features.

The client didn’t have any system tech documentation for the existing software products and only two in-house Delphi developers had all the related knowledge in their hands. That’s why the client asked us to develop tech documentation in order to:

Estimate the development costs as well as reach an agreement on the system functionality faster and more accurately

If it is required to expand the app, the documentation will facilitate the process of modernization and will let estimate the costs of adding new functionality to the existing system more precisely.

Reduce development time

When new developers come to the project, they see just a huge code with an unclear architecture and try to understand how to work with it. A significant part of work time is devoted to diving into the context (close analysis and study) and not to the development itself. That’s why the Softacom team had a key task to create documentation for 600 000 code lines, which would reduce the time needed for new developers to understand the project from 3-4 weeks (120-180 hours) on average to 20-30 hours

Reduce development costs

With technical documentation, a developer will faster understand what he is working on and will have fewer issues in accepting “heritage from other developers”. Without project documentation, a huge part of the development costs is allocated for studying “how it works”,” what it is” and “why it is so”. And it is nearly 30% of the project budget.

Facilitate code support and modernization processes

It is important to have a clear understanding of whether it is possible to integrate new functionality into the existing system in case of the necessity to expand the app.

Reduce risks related to the work of employees

When people leave a company, they take away the knowledge about the parts that they have created. The modernization and support of unclear parts become a very expensive task as it is necessary to study how everything is working at the moment and to build something new based on it.

Client`s pain and concern

Our developers have been upgrading and expanding our software for more than 15 years already but due to the lack of documentation, it is becoming more and more challenging for new experts to create additional features.
It is difficult to “predict” the right behavior of the system and every time when new functionality is added, something goes wrong.

We would like to find an efficient way to transfer knowledge to new developers for further maintenance of our software. And we are afraid that due to the lack of documents containing system descriptions the risk of its malfunctioning in the future is higher.

Without documentation, it is more difficult for us to estimate costs and terms for adding new functionality.

Project Team size

Business analyst
Project manager
2 QA engineers
Delphi developer

Solutions

We’ve divided the process of tech documentation creation into 3 important steps:

Step 1 - System overview

In the first turn, we’ve described the general functionality of the obsolete software:
– A list of separate system blocks where we’ve indicated the name of each block and their roles;
– A list of external interfaces – just like in the case with the block list but for external systems that the software products can be connected to;
– An architecture overview which is a diagram that shows how these blocks and interfaces are connected;
– A functionality overview which is a brief description of business tasks that the systems solve.

Step 2 - Detailed documentation

After describing the overall functionality, we’ve added a detailed description that explains the most complicated system aspects.

We’ve created diagrams of different software blocks and the interrelations between them. We’ve also described the scenarios of using blocks and described each code fragment in them.

The inherited code has a lot of exceptions from the normal stream. They all were introduced because of valid reasons. But it is rather difficult to find these reasons and sometimes completely impossible. However, we can document them.

Step 3 - Creation of a service and update schedule

Technical documentation is vivid content that should be reviewed and updated in accordance with new product releases or upgrades.

Technologies

used in the project

Delphi
MS SQL DB
DevExpress
RAD Studio XE3
VCL

Outcome

As a result of the documentation development, we’ve managed to add clarity to the understanding of obsolete software functioning. New tech documentation includes the description of programming code and its functions, data structures, algorithms, APIs, and interfaces. It also contains a detailed description of code functioning and the rules for using it.

We needed 3.5 months to create well-structured technical documentation with straightforward navigation. Now, end-users know for sure what they are reading. They can get a brief overview of all the information covered in documents and have contents with each step description which allows them to easily proceed to the most relevant part. No more senseless clicks and searches during code maintenance or new feature integration. It helps to save 40% of developers’ time and the company’s budget.

The developed technical documentation allowed the company to overcome its dependence on the knowledge of developers about the system’s functioning.

Now it is possible to plan a budget for adding new functionality, integration, or further migration with a high level of accuracy.