November 21, 2015

Reduce Transfer Problems with Self-documented Applications

In many application development projects it is a recurring problem: The application is documented both functionally and technically inadequate. As a result, the software is difficult to transfer and maintain. Modern development tools try to prevent this problem by keeping software and documentation together in one environment.

It already starts with the functional specifications: developers complain that it’s not clear what the customer wants exactly and what needs to be built. Then testers complain that it’s not clear what exactly should be tested. In addition, many programmers are also not a star in documenting. They prefer to program and assume that their code is so transparent and self-explanatory that it requires no documentation. The result is that the built business logic and design decisions are not clear, which then colleagues need to sort out the purpose or effect of functions or processes themselves.

In the beginning, when the application is still small and the original team is still working on the project, there is no problem. But as the project runs longer and the application extends, the problem becomes more and more pressing. And if there is documentation then it is often out of sync with the latest version of the application.

Modern tools make it easier to keep software well documented. Platforms similar to Pega and Mendix keep documentation and software together. User stories, use cases, process descriptions and even defects are recorded in the platform itself. This way everything is set in one place, namely the component itself, in the development environment. With a press of a button a Word or PDF document can be generated. Naturally it’s a discipline, which requires that use cases and explanations are registered properly. But the documentation does not have to be recorded in separate files. Moreover, images of processes and User Interfaces are updated automatically. Pega even knows the option to automatically generate screen shots of UIs that are filled with recently filled data. Also, that saves a lot of work.

The documenting of the software has additionally another advantage. It forces you to describe in plain language what has to be built or what has been built. This lets you automatically arrange your thoughts about the functionality that needs to be implemented. This will be reflected in the quality of the design and code also in the portability and maintainability.

In conclusion, human beings (read: business analyst, architect or developer) remain the weakest link. They must keep documenting accurately. But modern development tools and platforms make it a lot easier nowadays!

Jaco van Kooten – Senior BPM Consultant at BPM Company