%{
  title: "Swim the Test",
  author: "Willem van den Ende",
  tags: ~w(ATDD ComprehensionMaxxing CollaborationMaxxing),
  description: "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.",
  published: true
}
---

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](https://wiki.eclipse.org/images/2/20/Swim_System_PNSQC_2007_Paper.pdf). Plain spoken Paper by Ward Cunningham, Bjorn Freeman-Benson and Karl Matthias.

> 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.

!["Change personal address" Sequence diagram. 'Start' at the left, 'big2' and 'emo' column. big2 did some actions, and this results in 'User address changed'. Followed by some 'variations' (the swim paper in the linked post explains this). The 'emo' column has one 'emo address changed' box. Screenshot by Jon Udell](https://i0.wp.com/jonudell.net/img/visibleworking3.png?w=656)
Screenshot by Jon Udell.
[Jon Uddell's post]( 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](https://wiki.eclipse.org/images/2/20/Swim_System_PNSQC_2007_Paper.pdf) 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 ](https://www.youtube.com/watch?v=3tdmoj35HG0)
 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](https://www.linkedin.com/posts/matteovaccari_the-video-of-my-presentation-at-platmosphere-share-7478330775579586560-vSoX) in case you want to comment.

Matteo blogged about this earlier:
[Acceptance tests for AI Assisted development](https://matteo.vaccari.name/posts/acceptance-tests-for-ai-assisted-development/) on "grey box testing". Refers to [Approved Fixtures Pattern](https://lexler.github.io/augmented-coding-patterns/patterns/approved-scenarios/) and is also worth reading on its' own.

Visible Workings
---

[Visible Workings]( https://web.archive.org/web/20110202132102/http://visibleworkings.com) 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](https://www.sue.codes/)  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.

[What comes after view source?](https://www.sue.codes/blog/afterviewsource/)

[Being intentional about friction](https://www.sue.codes/blog/whatfriction/) 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](https://mastodonapp.uk/@sf105/116991301858959311):

> ward and Bjorn’s “swimlanes” work for the Eclipse foundation was an inspiration. It’s a crime against software that it was left derelict.

