From Executable Specifications to Living Documentation
In my previous article on Collaborative Software Engineering (CSE), I wrote about the value of shared understanding, strong engineering practices, and fast feedback loops in software delivery.
Since then, I have kept thinking about one promise that has been around for a long time in ATDD, BDD, and executable specifications.
It is a very good promise.
Describe system behavior clearly. Execute it against the system. Let that become living documentation.
The problem is that, in practice, this still breaks down.
The challenge is not writing executable specifications.
The challenge is publishing them as living, interactive documentation without friction.
That is the gap I want to focus on.
The gap I still see
A lot of teams already know how to write executable specifications.
They may use Cucumber. They may use xUnit-style tests. They may use internal DSLs. They may even have a very good domain language that fits their business and their system well.
And in many cases, these specifications already do something important: they help verify behavior in CI and give confidence during delivery.
But that still does not mean the team truly has living documentation.
What usually remains is one of these outcomes:
So the verification is there, but the documentation value is still limited.
That is the problem as I see it.
For years, a lot of the tooling in this space has focused mainly on authoring and execution. Much less attention has gone into publication, accessibility, and keeping behavior visible in a form the whole team can actually use.
And that distinction matters.
A framework can help me write and run scenarios. That does not mean it helps me publish the behavior of the system in a way that is accessible, dynamic, trustworthy, and useful to everyone involved in delivery.
Why this matters so much
To me, the value of living documentation is not that it gives us nicer documentation.
Its real value is that it closes the feedback loop across the whole software delivery team.
That includes developers, testers, product people, business stakeholders, domain experts, and users close to the business side of the system.
When the behavior of the system is visible, current, and grounded in executable specifications, the conversation changes.
We no longer have to depend so heavily on source code to reverse-engineer behavior. We no longer have to go back to stale PBIs or forgotten user stories to recover intent. We no longer have to rely on one domain expert explaining again how the system works or should work.
Instead, the team can work from a shared and reliable view of system functionality.
That matters because it improves engagement in the software lifecycle. It improves knowledge sharing. It makes it easier to analyze the impact of change. And it increases confidence, because the documentation is not detached from reality. It is tied to behavior that is actually verified.
That is why I do not see living documentation as a secondary artifact or a nice-to-have.
I see it as part of the delivery capability of a team.
It should help us understand the past, navigate the present, and change the future of the system with more confidence.
And if we do it well, it should contribute to software delivery becoming more predictable and more reliable.
What I do not want to build
One possible conclusion from this problem would be: build a better BDD framework.
Another DSL. Another syntax. Another Kotlin-first alternative to Cucumber. Another opinionated way to force teams to express behavior.
I do not think that is the right direction.
That would still put the burden on developers to adopt yet another authoring model. It would still assume the solution is to standardize how everybody writes specifications, instead of solving how those specifications become usable living documentation.
That is not what I want to build.
I do not want a tool that tells teams:
rewrite your executable specifications in my format.
I want the opposite.
I want teams to be able to keep the languages, frameworks, and domain-specific abstractions that already make sense for them. I want them to keep the DSLs that are truly theirs, shaped by their own business language and problem domain.
That means the problem is not “how do I replace their way of writing specs?”
The problem is “how do I make their existing executable specifications publishable as living documentation?”
That is a very different problem.
The direction I want to build
What I want to build is not another BDD framework.
What I want to build is a publication platform for executable specifications.
The idea is simple, even if the engineering behind it is not.
Teams keep writing executable specifications in their own stack. The platform ingests those specifications and their execution results. Metadata enriches them with documentation structure and business context. The platform then publishes them as living documentation that stays synchronized with CI.
That means the platform owns the translation, projection, and publication layer.
Not the primary authoring experience.
This distinction is central to the whole idea.
The platform should not tell teams how to write behavior.
It should say:
bring your executable specifications, your metadata, and your verified execution evidence, and I will turn them into living documentation.
That is the direction that interests me.
Why notebooks are such a strong fit
Part of what makes this direction compelling is the publication medium.
Static documentation is usually too fragile. Test reports are usually too narrow. Source code is too close to the implementation layer. Tickets and user stories are too easy to lose, fragment, or forget.
Notebook-based artifacts are interesting because they can bring several things together in one place:
That makes them a strong medium for living documentation.
Recommended by LinkedIn
I want to be explicit here, because this point matters a lot:
I am not proposing notebooks as the main verification mechanism.
Executable specifications should still be exercised in CI as part of the delivery pipeline.
The notebook should be the published artifact generated from that verified behavior.
That is the important distinction.
The executable specifications remain the source of truth for validation. The notebook becomes the most accessible and expressive projection of that verified truth.
That is where the value is.
The architecture direction
The more I think about it, the more the architecture becomes clear at a high level.
1. Executable specifications remain where they are
Teams continue using the frameworks, styles, and languages that make sense for them.
That may be Cucumber, xUnit-style tests, custom DSLs, Kotlin, Java, .NET, Python, or something else entirely.
The platform should adapt to the team, not force the team to adapt to the platform.
2. Adapters extract structure and results
Framework- or language-specific adapters collect the parts needed for publication:
This is how the system can support heterogeneous ecosystems without imposing a common authoring syntax.
3. A canonical model gives the platform a shared language
Once extracted, the information is represented in a common model.
That model should capture things like:
This is the real core of the platform.
4. Metadata enriches the documentation layer
I'm in favor of a sidecar model here because it avoids forcing intrusive changes into existing frameworks.
That metadata can define things like:
That way, teams keep their executable specifications, but can enrich them for documentation.
5. A renderer publishes notebooks
The renderer takes the canonical model and produces notebook artifacts.
Those notebooks should be readable, structured, traceable, and tied to the latest verified behavior of the system.
6. CI keeps everything alive
The publication flow should be part of the delivery pipeline.
That means:
That is how the documentation stays alive.
Not because somebody remembered to update it, but because it is continuously regenerated from verified behavior.
Why I think this is a broader engineering opportunity
The more I refine this idea, the less I see it as a testing problem only.
It is not just about BDD. It is not just about documentation. And it is definitely not just about syntax.
It is an engineering systems problem.
The challenge is designing a platform that can take behavior from different ecosystems, preserve business meaning, attach evidence and context, publish it in a dynamic form, and keep it synchronized with delivery over time.
That is a broader and more interesting problem than building another framework.
It also means the platform should be extensible by design.
Kotlin may be the right place for me to start. Jupyter-style notebooks may be the right first publication target. But the direction should be broader than that:
That is the ambition I see now.
What I believe is missing
For a long time, living documentation has often been treated as if it naturally emerges once executable specifications exist.
I do not think that is true.
Executable specifications do not automatically become living documentation.
There is a missing layer in between.
That missing layer is the publication layer.
It is the thing that gives executable specifications a way to become accessible, explorable, contextualized, and continuously synchronized documentation.
That is the gap I want to address.
Not by asking teams to throw away what they already have. Not by narrowing the problem to one framework or one language. But by building a platform that makes living documentation practical and operational.
Conclusion
The challenge is not writing executable specifications.
The challenge is publishing them as living, interactive documentation without friction.
And the reason that matters is not only better documentation.
It is better feedback loops. It is better stakeholder engagement. It is better knowledge sharing. It is better impact analysis. And ultimately, it is more predictable and more reliable software delivery.
That is the direction I want to explore and build.
Not another BDD framework.
A platform that helps executable specifications finally fulfill the promise of living documentation.
