It takes a village...
Last year I've had the pleasure of presenting at the Living Documentation Event. There, I talked about the challenges of building a Living Documentation solution in the current tooling landscape, and how a solution based on general purpose components might be the future of Living Documentation. Today, I have some interesting progress to report, and talk about why I feel that this latest revision I am currently working on, might actually be worth publishing as open source software.
This article is part of a series about BDD and Living Documentation with the theme "Building Bridges". Be sure to check out the articles of my colleagues as well: Kaspar van Dam on Agile and Compliance , Mark de Munnik on CARE-ing more about your customer , Christian Jansen on BDD without the tools and Derek Young on BDD use within the field of AI development .
Hopeful beginnings
Our journey starts at my previous assignment where I was asked to assist in the roll-out of Behavior Driven Development within the organization. While the first teams gradually got familiar with the methodology, we already started talking about an incoming problem with everyone's favorite subject: documentation.
As BDD was rolled out, teams started to follow all of the typical practices that come with it: writing their executable specifications in Gherkin, storing them as part of their development repository and automating them through their BDD framework of choice. As their collection of rules and examples grew, the legacy specifications were to be phased out to ensure the entire organization operated from the same source of truth. The problem was that these legacy documents had a considerable amount of users and stakeholders, that all highly valued the ease of access that came with them being “old fashioned” Word documents.
With BDD, the specifications were locked inside of the team's development repository, resulting in all of the users and stakeholders losing access to the knowledge captured in those executable specifications. As a solution, we chose to introduce Living Documentation. Living Documentation is - in short - documentation that is created, maintained and published in a way that ensures it accurately represents it's subject matter through-out that subject's entire lifecycle. At this point, our executable specifications already met all the criteria, except for the publishing part. But… There are tools for that!
Living Documentation giving lemons
And so we identified our requirements, chose a few popular tools that were capable of generating Living Documentation and built some Proof of Concepts with them to see how well they matched our use case. The answer was - to put it blunt - that they didn't. This was due to what and how most tools in this space work:
All of the tools were intended to generating test reports and provided little to no customization options. This made them extremely easy to use, but also meant their use case was extremely limited. Even something as seemingly trivial as adding an image or changing the color scheme turned out to be either a considerable challenge, or literally impossible. The only viable option was to build something ourselves, which was kind of bad news.
Let’s put on our management hat for a second: when developing something that isn't part of your core business, all effort spent on the development and maintenance of that thing should be scrutinized even more than usual to ensure that the benefits outweigh the costs. Because every minute spent developing a tool that we don't sell, could also be spent on developing a product that we do.
Time to make lemonade
We had a solid business case – no worries there - but this reasoning made us acutely aware of the risk of over-engineering our solution. If we were to make this a success, we needed to choose an approach that would minimize the burden of extending and maintaining it. Our strategy was to build a tool-chain where all of the heavy lifting would be offloaded onto general purpose tools that used proven technologies. By the time I left the assignment, the tool-chain we built had been handed over to be implemented in production, and looked something like this:
To summarize: the Gherkin Parser converts feature files into a format that compatible with the template engine, which outputs markdown files. By structuring the output in a specific way, the static website builder is able to transform the content into a fully functional static website. The only "custom code" needed are the templates to generate the markdown files, some structuring logic to enable building the website and some code to glue everything together. We had succeeded in our goal.
Tools are not an end, until they are
While we made great strides in our own little garden, I grew increasingly worried about the state of Living Documentation tools in the outside world. While our solution improved, the existing eco-system of tools had started to gradually and unceremoniously fade into obsolescence. Which was very, very bad. I might have my critiques, but tools like SpecFlow LivingDoc had always been invaluable to demonstrate the potential of BDD and Living Documentation. As those tools lost relevancy and gained technical debt, their use came with increasing caveats – making it harder to convince people of the value of Living Documentation (and indirectly, BDD). And as much as I believe in the value of those methodologies: at some point, I simply can no longer suggest them to organizations that do not have the scale and means needed to build and maintain their own solution.
But just as those kinds of thoughts started to get a hold on me, there was good news: the creator of Specflow and Specflow LivingDoc - Gáspár Nagy - broke through the silence. He said he was in the process of relaunching the tool formerly known as Specflow as an open source project under a new name: Reqnroll. I think my initial response to the news summed up my feelings nicely: relieved to finally see someone care, hyped to see Gáspár move back to his open source roots, and filled with a desire to somehow contribute to this cause.
With the news buzzing within ICT Improve, and realizing the importance of this news, we offered Gáspár a platform at our Living Documentation Event to brings us up to date on the recent developments, and what his future plans are for Reqnroll. We also invited him to be a part of our panel discussion: "The future of Living Documentation". A panel that I - as faith would have it - would kick off by presenting the Living Documentation solution we had built.
领英推荐
It takes a village
During the presentation, I spoke frankly about the issues and concerns I have already shared with you in this post: the limited applicability of the current tools, but also the lack of consistent support. During the panel, I asked Gáspár about the possibility of a “Reqnroll LivingDoc” solution and to paraphrase his (very understandable) answer: he needed to fully focus on rolling out Reqnroll and felt like maybe this challenge is better left to someone else.
Throughout the panel, the same pattern emerged: whenever the conversation veered into practical application, a call for help would soon follow. And this makes sense to me: we need to take a vested interest ourselves and collaborate as a community to build the tools that we need. Because if nothing else, Gáspár's experience with SpecFlow proved to me that we can't just rely on corporate interest to solve our challenges. It really does take a village to fix a problem. Just look at what I have shared so far: none of that would have been possible were it not for the open source communities that developed those general purpose we chose to use.
When Gáspár first shared “the news”, my response closed off with a bold declaration of intent: Although I have no idea how or when, I do know one thing: I want in. I still stand by that statement. It's easy to point fingers, but things that are worthwhile are rarely easy. And so, I look to myself: I am not a developer, I have zero experience in open-source development. Maybe this gut feeling I have about this idea having legs is nothing but idle hope. Maybe nobody cares… But there really is just one way to find out, right?
A solution revised
Ever since the Living Documentation Event, I've had this nagging thought in the back of my head: if you’re going to talk the talk, you have to walk the walk. But at the time I felt like something was missing. Like this thing we had built wasn't in its "final form" just yet. It needed more time, it needed an opportunity to be revisited and revised. I knew the way we used the static website builder left a lot of potential on the table.
Lucky for me, that opportunity came, when I was – once again - given the chance to demonstrate the power of BDD and Living Documentation. I wanted to dig deeper to see what improvements could be made. And as it turns out: there was plenty things left to improve:
This is the new revision of the tool. As it turned out, everything the template engine could do, the static website builder could do as well. So: out with the template engine. While I was working on the new templates, I – by sheer accident - realized that the JSON structure that the Gherkin Parser returned matched the Cucumber Message standard. So, if I would build my templates based on the output as is, I would effectively build a solution that is compatible with any source that was able to generate Cucumber Messages. And finally, I realized that - since all of the logic was now inside of the static website builder - it should be possible to package and distribute all of this functionality as a plugin or theme for the static website builder I was using.
A solution worth sharing
I think this revision of the tool might actually be worth sharing. Not now though: there is still a ton of work to do. Turning the solution into a plugin or theme is just an idea at this point, and although I've successfully proven that I can technically convert a feature file to a webpage, the current output just looks and reads terrible, so that's going to need quite a bit of polish before it becomes actually valuable. And although the team with whom I am building this revised "proof of concept" has the experience needed to make it work, the deal isn’t exactly sealed. Although I believe in BDD and Living Documentation, I also believe that it isn’t for every organization. The customer still comes first, so if I feel like this thing isn’t going to pay off fast enough for them, I will pull the plug and shelve it for another day.
Which brings me back to the title of this article, and you, my dear reader. Remember that post I quoted earlier? It has another line in it, just before the one I quoted: when people who develop software are guided by purpose over profit, beautiful things can happen. So what if… We would simply choose to not shelve it? What if… We would work on this thing just for the sake of discovering what value can come from it? What if… This actually turns out to be a solution worth sharing?
And what if you help me find out?
Be sure to tune in for our next blog in the series on the strategic value of BDD in test automation, written by Marlon Gerard and scheduled to be published 14 November!
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 previously published blogs: