Another look on tech

My thoughts on tech.

Augment your knowledge during software modelling sessions: Decision Log

02 September 2019

The most important learning during my career is that the act of creating software is a team effort. We can be a one-person team, but there is someone else involved; at least someone to use it.

As time goes by, I started to focus more on the collaboration between team members (and also teams, but it’s beside the point). The most effective collaboration techniques that I experienced are visual collaboration techniques. Amongst them, you can find EventStorming, Specification by Example, Impact Mapping or Example Mapping (I could be here all day).

I observed and facilitated in different settings; most of them are new teams inside of organisations that were set up to break legacy software, often intertwined. The teams are invested in crunching the knowledge before start coding the new solution, and part of the process involves making decisions that can impact the project.

Given the complex contexts in which the teams operate, it’s common to have several modelling sessions, spanning multiple days. During these sessions, the teams make strategic and tactical decisions, based on the knowledge that was crunched. However, not all these decisions stick in our mind, and I observed (and felt into the same trap) people to get over to the same topic, and not been able to recall the exact sequence of events for the decision.

To promote effective sessions, I started to use a visual technique, inspired by a pattern from Living Documentation, the Decision Log:

Decision Log - © All rights reserved

Decision Log - © All rights reserved

The biggest benefit of this visual technique is that it works as a quick aid for past decisions, which can be easily consulted during the session. On top of that, it’s analogue, thus keep the focus on the session.

However, I strongly advice (and do) to have the decisions on a more reliable format. For that, I suggest the usage of the Architecture Decision Records, for which there are several templates, and the team can leverage the source code repository. As a rule of thumb, after the session, the team (or a team member) writes it down using the agreed template.

And you? How do you augment the knowledge during a modelling session?