TLDR;
Every application has some kind of workflow. Understanding larger workflows, making them cohesive and understandable to users and developers is non-trivial. I re-discovered Ward Cunningham's Swim the Test approach, this is the Further Reading section of future posts.
[Jon Uddell's 2008 post about Ward Cunninghams' implementation of Brian Marick's 'Visible Workings'] https://blog.jonudell.net/2008/03/04/ward-cunninghams-visible-workings/ is a succinct introduction . connecting the Visible Workings pattern to the implementation made for a workflow system on behalf of the Eclipse Foundation.
The "Swim" System for User-Oriented Presentation for Test-Case results. Plain spoken Paper by Ward Cunningham,
Perhaps the highest compliment we received was when one of our customers (SC) said that she easily understood how everything worked because it "uses her words" in the interface panels and documentation.
Why this post?
Refactoring integration tests towards Swim the Test turns out to be easier than to write about it. And was not as hard as I thought - it can be done in baby steps. I keep both losing the literature references, and at the same time finding more or them. So getting them out of the way should help me post a 'how' post more easily.
Swim the test
Finally you can swim the test. Here the steps and results are laid out in a table. Time advances as you move down the rows, and there’s a column for every actor in the workflow.
Screenshot by Jon Udell.
[Jon Uddell's] https://blog.jonudell.net/2008/03/04/ward-cunninghams-visible-workings/ is a succinct introduction . connecting the Visible Workings pattern to the implementation made for a workflow system on behalf of the Eclipse Foundation.
The "Swim" paper
I learnt about the Swim system when Ward Cunningham ran a session about it at the first Agile Open Northwest (2006 or 2007 I think - this is a blog post, I may do the research later or it doesn't ship..)
The "Swim" System for User-Oriented Presentation for Test-Case results by Ward Cunningham Bjorn Freeman-Benson and Karl Matthias
I only found this paper existed now that I went looking for it. It also explained (when you read it back to front) on how to get started. The workflow with swimlanes looks very sophisticated. It mentiones run.php further down, which is 'just' one flow with some screenshots.
The reason I was attracted to domain modelling (long before Eric Evans' 2003 DDD book) was this:
Perhaps the highest compliment we received was when one of our customers (SC) said that she easily understood how everything worked because it "uses her words" in the interface panels and documentation.
Simplicity is achieved when there is nothing left to take away. Compare this to DDD's "Ubiquitous Language". The scare quotes are intentional. As a non-native speaker I had to look up Ubiquitous. Compare this with the paragraph above. I appreciate many of the user-focused things that come out of the DDD community, like Event Storming, but ask yourself, if a patterns introduce barriers to outsiders, or if it removes them (and when introducing barriers, is the trade-off worth it?).
At the same time, our abstractions are detailed enough to be believed because we are running the real code in our simulations instead of bubbles and arrows diagrams. We respect the user's expertise without dumbing down our system or forcing them to use our terminology.
A large application is built in many small steps
This looks like a lot of work, and I haven't integrated this in an application. Yet. Reworking existing integration tests to output dialogs as HTML for each step was not that much work, and the rewards are instantaneous: multi-step workflows now become glanceable. And as they get longer, I can make small improvements to improve glanceability.
I am trying to draw in the users as well, let's see how this goes.
Further, further, Reading
This is meta - a Further Reading section in a further reading post ;-).
A harness for behaviour
I was reminded of the swim system by this talk of Matteo Vaccari on youtube which focuses on tests that are understandable by the stakeholders. A Harness for Behaviour: Ensuring Ai-generated Code Does What We Want - TDD in the Age of AI He referenced Fit and focuses on writing tests that work as a communication medium between users, stakeholders and developers. He uses an external DSL in YAML. I am not against YAML, but someoone's remark last year that all new programming languages appear to be YAML gives me pause, whenever I see it. The main thing is when it works it works. Context is key. (not further reading: I ended up with an internal DSL and screenshots in small steps as a medium - the users don't need to be able to write tests, yet, communication about what we are building and how it works is key. In small steps - I don't believe good UX comes from large batches). LinkedIn post on Matteo's account in case you want to comment.
Matteo blogged about this earlier: Acceptance tests for AI Assisted development on "grey box testing". Refers to Approved Fixtures Pattern and is also worth reading on its' own.
Visible Workings
Visible Workings on archive.org, as the original site is no longer active. I like the notion of "Tinkerable Software".
Explanatory software goes hand in hand with tinkerable software because the dedicated amateur will need explanations to do the tinkering well.
"View Source"
A comment in one of Jon Udell's posts about 'View Source' reminded me of the work of Sue Smith My timebox is up, she has a great blog in which is she writes about building tools in an IDE to make software development accessible to newcomers. I remember her writing about how to replicate the 'view source' experience of early web 2.0, where you could find out how a web front-end worked by 'just' viewing the source.
Being intentional about friction is more tangential, and inspiring. Some comment about the link to the tests in an application on one of Jon Udell's 'swim' posts may be related. That link to the tests inside an application dialog may be seen as friction, but also, as Sue puts it:
Removing friction does not necessarily empower people
and
Being able to choose which details are worth paying attention to is the trick.
Happy reading and watching
Thank you for making it to the end. I hope this inspires you to do more reading, watching, and more importantly, building.
As Steve Freeman put it just now:
ward and Bjorn’s “swimlanes” work for the Eclipse foundation was an inspiration. It’s a crime against software that it was left derelict.