A Model Project

And this is how it goes. One thing to another ...

At the weekend I  was listening to Gene Kim's Idealcast interviews with Dr. Nicole Forsgren and Jez Humble. Jez Humble was talking about the importance of rapid feedback and referenced a Brett Victor talk that had stuck with him over the years:

... he built this little JavaScript game and he was changing parameters and the game was changing in real time. And his whole comment is like, if you can change something and see the change as you are changing it, it's incredibly powerful.  

And so I looked it up in the show notes and watched it. Wow ...

Inventing in Principle shows examples of experimental tooling for creative activities, particularly those that include a temporal dimension. The essential idea is to reduce the friction of having to maintain a model outside of the tool.

In the image at the top, the left side is a traditional IDE and the right side is a dynamic visualisation of the function being developed. You might imagine this is some kind of fancy trace left by a debugger. You'd be wrong. 

The view on the right updates as the code or inputs are edited ...

Without this, programmers model data flowing through the algorithm in their heads, perhaps augmented by a static surface such as paper or a whiteboard, sets of inputs and outputs, by printing or asserting at tactical locations, or stepping laboriously through the execution. 

Victor's approach doesn't remove the need for a model but it does make the item being created into an explorable example which means that its much easier to ask it questions, test it out under different conditions, and develop an intuition for it.

The term explorable example is new to me, but the approach is not. I use spreadsheets extensively to explore data and behaviour. But spreadsheets are another model, an abstraction on top of the system I am actually looking at.

And so I got to thinking about models ...

I recently joined an early stage project which is building a service to expose a new API but calls into an existing service for most of its functionality. The core personnel on the project  work together on the existing service. The API has been designed by our architecture group. I come from a third team.

As we began to explore the proposed API and its relationship to the existing service, it was interesting to observe the models that were created individually and collaboratively. They included:

• A specification for the new service written as an OpenAPI document. Deliberately clean-roomed to avoid biasing towards implementation details of the existing service, it also looked forward to a more general service that might come later. This model aimed to subsume the functionality needed for the specific project but at the same time was incomplete around error handling and a particular subset of endpoints where stakeholder needs were still unknown.
  
• A mapping between the endpoints and request payloads of the new and existing services in a simple table. This model sanity-checked that the data required for any supported transaction would be available, identified places that state might need to be preserved in the new service, and flagged similar concepts with different names and different concepts with the same name.
• A Miro board describing user interactions with a client UI that would call the new API. This model was helpful because it reminded us that there was a human base to this project, and it had been built in collaboration with our stakeholders. It also showed multiple alternative paths through the client application and hence implicitly the API.
  
• A sequence of request-response pair mock-ups between the new service and some client as JSON, in a Markdown file. This model was particularly valuable for those familiar with the existing service because, in their heads, they could already align it with the new service. It also meant that we could model an end-to-end workflow very quickly.
  
• Another Miro board model which also modelled the end-to-end journey but abstracted away almost all detail to focus on just two data types. This was helpful because those types needed to be carefully matched across the two services.
  
• A request sequence flow diagram following data from the external client through the new service to the  existing end, and back, in a spreadsheet. Similar to the JSON model in some ways, but covering both services, losing the structure to focus on what data items were passed, and, much more visual. Request and response were aligned horizontally and time was represented vertically.  Additional richness came from colour to highlight particular data items or questions and columns for commentary. All these advantages came at the expense of significantly more effort to set up and drive.
  

And so I was thinking about the value of the models ...

Those models were all explorable to some extent, at the cost of the mental and physical friction of needing to keep track of context and state. In particular, none of them were parameterised and none of them updated dynamically. 

Some of the models were compiled and abandoned relatively quickly, perhaps having given some insight which prompted a change in direction or proving too costly to build and drive. The spreadsheet model was dropped and then returned to after iteration had happened elsewhere.

Despite the shortcomings, they were each helpful in facilitating conversation and understanding and iteration on the idea we were trying to bring to life. 

Interestingly, although they were shared, they served different purposes for different people and consequently had different value to different people too. The knowledge we carry with us in our heads can be reflected by the absence of that knowledge in the models we make.

And so I was thinking about the way we approached the models ...

We moved back and forth between the models as our conversations progressed. A simpler model might be used to sketch something out and then a more complex model would explore the detail around it.

At some points we cross-referenced the models with labels representing equivalent states but I doubt there was a time when any one of them told the whole story of our growing common understanding.

This isn't a surprise. In the context, there was an enormous amount of fluidity. If we noticed something that  we thought might not work there were multiple places that we could make a change, including the API specification itself.

We could also choose when to make a change. At one extreme, we could keep possibilities open, seek patterns, and look holistically for some pragmatic trade-off. At the other, we could make an immediate change, reduce local uncertainty, and see what fell out later. Both gave us a way to move past a problem, with obvious pros and cons. 

And so I was wondering whether there was any conclusion ...

Not really. I'm just trying to get my thoughts in order. Perhaps if you pushed me I'd say this:

• none of these models were explorable in the Brett Victor sense, although we did explore the models extensively with the tooling and perspectives we had
  
• the feedback was not always fast in the Jez Humble sense, but by making tacit knowledge explicit and talking it through we got extremely valuable feedback, and we acted on it.
  

Image: Brett Victor