Living Documentation

Living Documentation

• Living documentation in legacy systems

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.

---

• What is Living documentation
• Living Documentation vs. Test Reports: What's the Difference?
• Chapter 11. Living Documentation: reporting and project management

---

• File Header
  • FileName
  • Description
  • Requirements
• Method Header
  • Method Name
  • Description
  • Parameters
  • Requirements
• Change Logs
  • Requirement
  • Todo

---

• Step-by-step guide for LivingDoc Generator — SpecFlow+ LivingDoc documentation
• Use JSDoc: Index
• Serenity/JS | Serenity/JS (serenity-js.org) - Next generation acceptance testing.
• TSDoc - a proposal to standardize the doc comments used in TypeScript.
• TypeDoc - A documentation generator for TypeScript projects.
• BDD Testing & Collaboration Tools for Teams | Cucumber
• Pickles - the open source Living Documentation Generator (picklesdoc.com)
• PactumJS - REST API Testing Tool
• SolidJS · Reactive Javascript Library
• The Fastest Frontend Framework for Headless CMS's | Gatsby (gatsbyjs.com)
• Build optimized websites quickly, focus on your content | Docusaurus
• JavaScript End to End Testing Framework | cypress.io testing tools