Many moons ago, when I used to write software, I realized I was misinterpreting stakeholders, and they me. We were using the same words, but thinking of different things.
Misunderstandings#
Over a period of time sales, support, and product were getting annoyed with me for ’taking too long’ to build simple things, or ‘delivering rubbish’ too quickly. I was deeply confused. How could I possibly be taking too long on some projects, and not building quality solutions, at the same time?
After (probably too long), I realized I was being told one thing, but through the various layers of engineering process, we were building the wrong thing1. It reminded me of a very old image, which visually depicts the differences in what a customer needs, and what is delivered to them.
Specifically, when I was being asked by sales to build a quick prototype for a customer, I was building a ‘bells & whistles’ grade solution. And then, when I was being asked to build a ‘production’ grade solution, I was building a prototype2. We were using the same words to explain what we wanted — like ‘production’, ‘prototype’, ‘alpha’, etc. — but we had different ideas of what they entailed.
Obviously, we needed to agree on what words meant. When they said the customer wants a prototype, what does that mean? When something is production, what is it?
A Vernacular Cheat Sheet#
Vernacular (noun)
The form of a language that a particular group of speakers use naturally, especially in informal situations.
Agreeing on what a word means is hard because to do that, you need more words which you might not agree on.
So I came up with a cheat sheet. Thirteen properties, shown on a single side of A3, which we could put up on the wall and agree on. These properties seemed like the most important things to me at the time, and if you look at a delivery from a technical lens, they probably still are.
Splitting the quality of software down into ‘alpha’, ‘beta’, and ‘stable’; where quality increases from one to the next, but so does the amount of time required to build it. Importantly I avoid the use of the word ‘production’ here. Production is overloaded as a term, and is commonly used to describe a deployment environment. ‘Alpha’ code can be in production, for example.
I have tried my best to recreate the cheat sheet in some lovely CSS.
Your screen is a bit too small, so here is an image instead.
Is the feature accessible to a customer?
Ensure the system display the behaviour of the feature?
Does the user documentation allow users to understand the API?
Can the on-call team tell if the system is running as expected?
Can we guarantee behaviour to the end user? Will it change?
What level of coverage is mandatory?
Should we be refactoring code to make it cleaner as we go?
Are we going to manage the customers expectations downwards?
Will we be monitoring/checking the data quality of the feature?
Will an on-call operative be woken up if this feature breaks?
Will automated code quality checks be satisfied?
What (non)functional areas will the requirements cover?
What will be covered in development reviews?
Will it fulfil the requirements?
Code conformance
Test quality + Design + Architecture
I WANT the possibly-flaky feature to be developed quickly and cheaply
SO THAT I can gauge interest in a feature and see if it will encourage sales.
I WANT the beta feature to be of reasonable quality
SO THAT I can work with a customer to develop the feature into something reusable and stable.
I WANT the stable feature to be of good quality and reliability
SO THAT I can sell the existing feature to new customers and promise them good SLAs that they will pay £££ for.
I WANT the customer's expectations to be managed and no SLAs to be required
SO THAT the business doesn't make SLA commitments for quick proofs of concept.
I WANT a reasonable level of testing
SO THAT the beta feature can be iterated on easily with a reasonable degree of confidence.
I WANT full system tests
SO THAT the stable feature can be maintained without causing regressions.
I WANT no alerts to go off if the possibly-flaky feature breaks
SO THAT I'm not being woken up at 2AM for no reason.
I WANT a reasonable level of monitoring (and possible in-hours-only alerting)
SO THAT I can gain confidence that the beta feature will not cause lots of incident when it goes stable.
I WANT good monitoring, alerting, runbooks and outage drills
SO THAT I only get called out to deal with actually SLA-impacting incidents and when I do, I can actually fix them.
So, as an example: if Sales asked us for an ‘alpha’ feature, we would deliver something that met the basic functional requirements, but might fall over, and the customer would find out, not us.
Critically, Sales should have managed that customers expectations that they were getting something quick to try, but ‘stable’ it would not be.
If Sales came back to complain, we could tap the sign.
The primary output of this was that we ‘were on the same page’, but it also helped each department gain confidence in one another. Sales were no longer worried we were going to ‘over-engineer’ quality into something when it wasn’t needed, and engineering were not worried that something we built in a rush would wake us up at 4am.
Parting Thought#
Whenever I use the phrase ‘we are on the same page’, I think of this quote:
“Are we all on the same page, Delilah?”
“The same page? I don’t even think we’re even in the same library.”— Sarah Ockler
