Crossing the bridge: Agile and Compliancy (1)
While the Olympic and Paralympic Games are almost at an end I would like to take this opportunity to start a new series of blogs together with my colleagues at ICT Improve . This upcoming year we will post a new blog every two weeks about building bridges? in IT. We do this with topics like for instance Behaviour Driven Development, Domain Driven Design, Impact Mapping, Event Storming and more in mind. All methodologies that are about collaborating, communicating with a shared goal to effectively deliver the best possible software for an end-user (see all currently published blogs at the bottom of this article). This first blog will be about Agile and Compliancy. Two things that seem to contradict each other, that are near impossible to merge… But are they, really? We think there is a way to cross the bridge between Agile and Compliancy and this bridge is called “Living Documentation”.
What is this thing called Living Documentation?
According to the Glossary of CARE (Capturing Agile Requirements by Example: https://www.agile-united.com/) Living Documentation can be described as follows:?
Living documentation is a dynamic method of system documentation that provides information that is current, accurate and easy to understand. Feature files that are written in a natural language format may serve as the core of living documentation. Each file describes how a particular piece of functionality/code is supposed to behave, gives example(s), and describes the desired outcome. It can be used for documentation purposes, as part of the acceptance tests and as input for (automated) tests and coding (executable specification).
Loosely translated this means two things:
This can be done using a methodology like Behaviour-Driven Development and implementing Specification by Example which in turn uses many elements from Domain-Driven Design.
?Why Living Documentation?
To answer this question let's start with a little bit of history on software development. These days it's quite common to use an Agile methodology when developing software. But when we talk about “Agile” we usually refer to the Manifesto that was created in 2001. However, the ideas behind the Agile way of working go a lot further back. Already in the 1950s and 60s NASA was using iterative and incremental development methodologies, for instance Project Mercury, and also IBM applied these ways of workings during that same period?(Larman & Basili, 2003). Throughout the years iterative and incremental software development kept being used but for a long time a more linear approach (Waterfall, V-Model) became the de facto standard. The Agile Manifesto was created in 2001 as a response to those linear methodologies making software development more adaptive, iterative and incremental and also more people oriented (Abbas, Gravell, & Wills, 2008).
One of the reasons linear methodologies became so popular for a long time had everything to do with documentation. Working with computers and developing software quite quickly became very complex and as an industry we realized we could only keep track of things through extensive documentation. So, we wrote big documents and asked many people to review those and put their signatures on it before even considering starting spending a lot of money on developing that complex software. But as technology progressed software development became more and more about experimenting and less and less about having extensive documented designs and predictions on the software’s behavior beforehand.? That’s where the Agile Way of Working became much, much more suitable for most environments except for, for instance, environments where compliancy was important. In those environments you do still need a lot of documentation explaining what the software should be doing and proof that the software is actually doing what is in that documentation. That meant a lot of requirements traceable to tests, traceable to the actual software product. And this is holding back the development of software in many of these environments. A good solution to that would be a way to have this extensive documentation traceable to tests and the software while still being able to go about it in an adaptive, iterative, incremental and people-oriented manner. And that’s exactly what Living Documentation can do for you.
Our vision on Agile and Compliancy using Living Documentation
We think that in today's world Compliancy and Agility can be combined, and even more so: should be combined to get to a more LEAN way of developing a product or software in a compliant environment. Even when we’re talking about high-risk environments like the medical sector (FDA) and also when talking about embedded software (hardware products, self-driving cars, medical robots, etc). For this we resort to proven methodologies like Behaviour-driven Development, Specification by Example, CARE. And we work to make Living Documentation an integral part of the development process. In order to make that work we developed a blueprint of a toolchain using standard tools that reduce the compliancy-burden while also making it more standardized and (therefore) reliable, by using automated evidence generation. However, this only works if everyone involved is also onboard and competences work together: Business, QA, Development, Hardware development, Software development, etcetera.?(de Munnik, 2023) This matches the people-oriented approach of the Agile Way of Working.
At the Living Documentation Event 2023 my colleague Mark de Munnik presented our vision on how to implement Living Documentation into a project and/or organization where compliancy is required. Below is the roadmap to follow:
In most organisations part of the things mentioned in the roadmap are likely already in place, the roadmap can be used to pinpoint the gaps and to come up with a strategy on how to fill those gaps and cross the bridge between Agility and Compliancy.
For this blog series there’s (at least) two things from this roadmap on which we'd like to elaborate a bit more: CARE and the toolchain. I’ll be focusing on people and process in this blog (CARE) and in a future blog Johan V. will elaborate more on the required technology (the toolchain).?[edit 31/10: this blog has now been published here]
CARE: Capturing Agile Requirements by Example
CARE is the methodology we developed at ICT Improve many years ago and which is now an internationally certified way of working. While it’s based on the principle of Behaviour-Driven Development there’s more to it. It’s mainly about how to collaboratively get from an idea to a concrete product. The main goal is to get a shared understanding of what exactly an end-user of a product wants and needs and to find ways to unambiguously describe this in requirements and use these requirements as the first tests for the software to be developed according to the principles of Acceptance Test Driven Development (ATDD). To achieve this there’s different stages the team and all stakeholders need to go through together, starting with getting a clear understanding of the big picture. For this you can use Impact Mapping?(Adzic, 2012), but Big Picture Event Storming is also suitable?(Brandolini, 2021). From this big picture we start refining, this can be done by organising one or more “Three Amigo”-meetings where representatives of the different involved disciplines discuss what the end-user needs from the product to be developed. This can be done using Event Storming and made more concrete using Example Mapping where we describe a story with its rules and underlying examples?(Wynne, 2015). Finally, these examples can be formalized and written out using the Gherkin-format: Given the following prerequisites, When an end-user performs this behaviour, Then the system has responded with that behaviour. For a more detailed case study on CARE, see the article published by the BDD workgroup at Testnet: Case Study Behaviour Driven Development Part 1 - TestNet.
The resulting so-called Feature-Files with story, rules and examples can now be used to make automated acceptance tests that will eventually proof the software to be built actually does what it is supposed to do using the right tools
Toolchain: A proof of Concept
As presented by Johan V. at the Living Documentation Event 2024 it is possible to create a tool chain that will automatically generate documentation based on the feature files and including test results using an off-the-shelf static website builder?(van Berkel, 2024).
?This diagram shows a simplified implementation of how this could work. What makes this a great solution is that it’s proven technology which can be implemented using existing off-the-shelf tools while still being very flexible and extendable. What makes this very suitable for environments where compliancy is important is the fact that documentation is (partially) generated from the feature-files and combined with the results from the run acceptance tests based on these examples in the feature files. There is a single source of truth, and everything can always be traced back to it. There’s a direct link between requirements, tests and the delivered software. As said, more on this toolchain in the future blog of Johan van Berkel.
Conclusion
With Living Documentation and the CARE methodology we have created the bridge that connects the Agile world with the world of Compliancy. This makes it possible to develop high-risk products, like medical devices, self-driving cars, etcetera, in an iterative, incremental manner with a people-oriented approach.
Want to know more? Feel free to get in touch or leave a comment! And definitely don’t forget to (pre-)register for the Living Documentation Event 2025 if you want to be part of the community that makes things like this possible! You can (pre-)register here: https://www.ict.eu/nl/evenementen/living-documentation-event-2025.
References
Abbas, N., Gravell, A. M., & Wills, G. B. (2008, June). Historical Roots of Agile Methods: Where did "Agile Thinking" Come from? Lecture Notes in Business Information Processing.
Adzic, G. (2012). Impact Mapping. Provoking Thoughts.
Brandolini, A. (2021). Introducing EventStorming. Leanpub.
de Booij, D. (2024, August 28). Case Study Behaviour Driven Development (Part 1 + 2). Retrieved from Testnet: https://www.testnet.org/artikelen/case-study-behaviour-driven-development-part-1/
de Munnik, M. (2023). Agility & Compliancy: A bad marriage? Living Documentation Event 2023 (#LDE23). Eindhoven.
Larman, C., & Basili, V. R. (2003). Iterative and Incremental Development: A Brief History. Computer (Published by the IEEE Computer Society), 2-11.
van Berkel, J. (2024). Shaping the Future of Living Documentation. Living Documentation Event 2024 (#LDE24). Eindhoven.
Wynne, M. (2015, December 08). Introduction to BDD Example Mapping . Retrieved from Cucumber Blog: https://cucumber.io/blog/bdd/example-mapping-introduction/
?
?All blogs in this series
This blog is part of a series of blogs published by ICT Improve around the theme “Building bridges in IT”. Every two weeks a new blog will be added using the hashtag #BridgesinIT. Also see the currently published blogs: