Enable javascript in your browser for better experience. Need to know to enable it? Go here.
radar blip
radar blip

Living documentation in legacy systems

Published : Oct 27, 2021
Oct 2021
Trial ? Worth pursuing. It is important to understand how to build up this capability. Enterprises should try this technology on a project that can handle the risk.

Living documentation, which comes from the behavior-driven development (BDD) community, is often considered a privilege for those well-maintained codebases with executable specifications. We found that this technique can also be applied to legacy systems. Lack of business knowledge is a common obstacle encountered by teams when doing system modernization. Code is usually the only trustworthy source of truth because staff turnover and existing documentation are outdated. Therefore it's very important to reestablish the association between the documentation and the code and spread the business knowledge among the team when we take over a legacy system. In practice, we would first try to go to the codebase and deepen our understanding of the business through simple cleanup and safe refactoring. During the process, we'll need to add annotations to the code so that we're able to automatically generate living documentation later. This is very different from doing BDD in green-field projects, but it's a good start in legacy systems. Based on the generated documentation, we would try to convert some of the specs into executable high-level automation tests. Do this iteratively, and eventually you could get living documentation in legacy systems that is closely associated with the code and partially executable.

Radar

Download Technology Radar Volume 25

English | Español | Português | 中文

Radar

Stay informed about technology

 

Subscribe now

Visit our archive to read previous volumes