Understanding things is hard. Explaining things is harder. This article intends to help you communicate and reason with clarity using simple questions to contextualise your work. It’s written with software in mind but is more broadly applicable.

The problem of de-contextualised information

Let’s consider two problems.

The first problem is describing and understanding systems. Let’s not get too hung up on the definition of a “system” - let’s just think of it as a bunch of computer stuff that does a thing. Imagine you’ve started working on a new project, an existing system that you’ve never even heard of. One of your colleagues tells you about it:

“The McGuffin sits here, there’s a FooBar service here, this pushes artifacts to the Grok Harvester, the hip bone connects to the thigh bone, etc etc…”

Now, that’s all well and good, but it’s only a static description of a system and is completely devoid of context - I wouldn’t feel comfortable starting to hack about on it just from this.

The second problem is understanding why you’re doing what you’re doing (whatever that may be). Picking up a story from a backlog and working on it is a commendable thing to do, and stories are (or should be!) well defined with clear acceptance criteria. The danger is that the ticket becomes an end in and of itself - you are “doing the ticket” rather than working on a broader goal.

Contextualising system descriptions

The first problem we looked at is describing systems. In our example, we received a “polaroid”-like description of a system - a snapshot at the current point in time. To help us increase clarity, we need to acknowledge that all systems don’t just exist as a singularity in the here-and-now - they have a past and a future, each dripping with useful information.

Here is a model of a system, contextualised in both the past and the future:

Fig 1: Contextualised system model

Here, we see that the middle section, “things as they are”, can be considered to be state - it is what it is, in short! This is vital information, and it’s what you have the most data on because you can inspect the system in real time. However, it’s only really a small slice of the “story” of the system. Like us humans (and any sentient AIs who may be reading), the system also has a “where it’s been” and a “where it may go”, and these slices contextualise the state.

Questions to help with system contextualisation

So, we need to communicate the broader story - moving from a “polaroid” to a “VHS” (yes I’m aware that both technologies are obsoletish but physical metaphors are refreshing when you spend all day with digital). When I’m describing a system, I find it helpful to ask a couple of questions:

1. What problem is the system solving?

Rather than starting with “this system is”, start with “this system solves problem X”.

For example, instead of “this is an artifact repository”, you could say “we needed somewhere for the QA environments to pull the latest code from without exposing them to production, so we created a secondary artifact repository.”

The benefit of this approach is that the person having the system explained to them sees the need for the system

2. What have been the big pivots?

Very few systems have a smooth path from inception to present - most have big changes along the way (that we’ll call “pivots”) and these can be very instructive. You’re just looking to give enough information for context at this point, not the entire history of every single minute decision, every commit, every sweaty palmed rollback… You just want the broad strokes - big pivots in the system’s history.

For example, “we used to use Angular for our widgets, but a year ago we switched to React, however some of the Angular stuff’s still in use for some customers”. That’s far more useful than “we’ve got some React and some Angular”.

3. What’s next for this system?

A system exists in the present and into the past. It also exists into a future that becomes murkier the further away you move your perception from the present (an effect known as the “cone of uncertainty”). However, you do likely know the broad strokes of what is planned for this tool.

So, saying something like “we’re going to gradually phase this out as we migrate to using containers instead of virtual machines and replace it with a Docker repository” gives the recipient a sense of where this system is going.

It really helps somebody to understand the utility that the system has at present and in future. Perhaps, for example, this system is something that’s historically been business-critical but is now legacy. Conversely, perhaps this system was created as a “hero project” but crept into production (as such things do) and is now used by an increasing number of clients.

Contextualising tasks within broader goals

Fig 2: Contextualisation of tasks

Everything we do should come from our values. They’re the most important so I drew them the biggest with my crayons.

From our values, we derive goals. This can be anything - e.g. “create a system that does X” or “start a cross-functional team to handle Y”. If a goal doesn’t reflect our values, why are we doing it? If it doesn’t reflect the direction of the organisation, then why on earth is it even a thing? Kill it with fire!

Likewise, tasks are the little steps to achieve our goals. They should be understood in the context of the goal:

Fig 3: understanding in context

Here’s the same thing expressed in terms of Lego because Lego is mega and anyone who says otherwise is a hater:

Playing with bricks in isolation may be fun for 30 seconds but sooner or later you want to make something! Either way, you’re going to stand on one in the middle of the night and scream the house down.

One thing that tends to happen in software teams is people get hung up on “doing tickets”. I totally understand that - tickets are important for a sense of progression. When you slide that card across to “ready to review” you feel a sense of accomplishment. I think we all cherry pick the quickest and easiest tickets - I certainly do. It is, however, a risky fallacy - tickets are not an end in and of themselves. This is why it’s so important to continually evaluate our goals in the context of the organisation’s values, and pick our tasks accordingly. This is a key element of professionalism - to ensure we are not just busy, but busy building the things that really matter.

Questions to help with contextualising tasks

I’m sure some of the clever sausages in the Agile community would be far better positioned to answer this than a curmudgeonly socially inept code-stooge like myself!

All I’d say is, “how does this task get us towards the goal? How does this goal reflect our values?”. I don’t think you can go far wrong thinking like that.

Contextualising In the microscale

I’ve talked about contextualising in the macro scale - at system or project level - but it’s something that I think we all need to weave into every level of what we do.

One microscale issue of de-contextualised information is commit messages (or even pull requests) that don’t say WHY a change is needed. In fact, sometimes you’re lucky to get even a description of the changes! This is a huge assumption of knowledge and it totally hostile to newcomers.

Putting a ticket reference in is good, because I can refer back to the issue tracker to see what the commit is intending to solve. This doesn’t, however, tell me anything that a developer is thinking - I have to infer everything from the diff of their changes. Bad form!

This is just one example. Emails, instant messaging posts and meetings can all be harmed by de-contextualised information. There really is no such thing as trivial change.

Wrapping up

De-contextualised information is far less useful than contextualised information. Whenever you are communicating in any medium, consider the importance of context in the information you are providing. This doesn’t mean rabbiting on for hours, it’s simply about stopping and thinking before you communicate.