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
This blip is not on the current edition of the Radar. If it was on one of the last few editions, it is likely that it is still relevant. If the blip is older, it might no longer be relevant and our assessment might be different today. Unfortunately, we simply don't have the bandwidth to continuously review blips from previous editions of the Radar. Understand more
Oct 2021
Trial ?

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.

Download the PDF



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

Sign up for the Technology Radar newsletter


Subscribe now

Visit our archive to read previous volumes