3 asynchronous techniques to help you communicate about design
On agile teams, design is a continuous process - be it new ideas, new features or changes to the architecture or the technical solution. Writing is a scalable, and noise free way to communicate detail so you can exchange feedback and build consensus. This post addresses three techniques to communicate about design on an agile project.
- Idea papers allow you to nurture fresh ideas by articulating them clearly. People can use this as a reference to share feedback and enrich the idea. Consensus is also easier if everyone can understand the idea well.
- Feature breakdown documents serve as a single resource to catalogue all information about a feature. As the team enhances the feature, this document becomes a single source of truth about it.
- Design docs are an efficient way to communicate about software architecture and technical solutions. These docs precede an architectural decision record. They benefit from detail, though brevity is an important consideration too.
Over the last decade and a half, the agile movement has found ways to bring design to the centre of how we develop products. This has led to several little innovations in the way we design and deliver software; be it user story mapping, design sprints, dual track development or any other design thinking inspired approach you’re familiar with. The double diamond is a philosophy that encapsulates much of the modern thinking that goes into building software today.
The double diamond approach to building software
There’s a wealth of material about the double diamond, but here’s my attempt at a succinct summary, in the software development context. The inimitable Jonny Schneider inspires a lot of this.Building great products has four steps that work in synergy.
Discover. Every product comes to life because someone sees a trigger in the real world. You need time to understand this problem in some depth to know if it really needs a solution. If so, you should be able to figure out a bunch of ideas to address that real-world problem. This phase diverges to line up those ideas so you can move to the next step.
Define. Once you understand the problem and have a range of ideas to consider, you need to narrow your focus down to the ideas that need the most attention. Every development team has limited resources to make a dent in the universe. This phase seeks to identify the most impactful ways to make that dent.
Design. In this phase, we enter an iterative process. We have a vision in place by now. It’s time to solidify the solution by ideating, prototyping and validating with a range of stakeholders.
Deliver. And finally, the rubber hits the road. This is what most of us know as agile development. We build, we measure, we learn, and so the cycle repeats.
The first two steps aim to converge on the most interesting ideas to pursue; a.k.a “build the right thing”. The next two steps aim to bring those ideas to life; a.k.a “build the thing right”. I want to point something out here. The last two steps seem sequential, but they’re not. They can happen as parallel tracks. If we’re doing continuous delivery, we are also doing continuous design.
Just like with architecture and application design, some amount of up-front thinking is needed to set the framework for the user experience. However, again, just as with architecture and design, the focus should be on setting as little as possible initial framework, allowing the design to evolve along with the changing user needs and expectations. Continuous design as an approach allows for the user experience to exploit insights learned during the evolution of the system.” - Dr Rebecca Parsons, CTO Thoughtworks.
The process of continuous design is beyond the book or this blog. I want to focus on the communication of design. If we’re designing continuously, we’re also communicating about it all the time. In today’s post, I want to share three asynchronous techniques to communicate about design. Before that, however, I want to answer the all important question - “Why?”.
The blind people and the elephant
How consistently does everyone understand things on your project?
Software development is a costly business. That’s why we obsess over ways to reduce risk and to promote shared understanding - for example, smaller requirements as user stories; pair programming, blue-green deployments and audit trails. A lack of shared understanding at the delivery stage can be chaotic, and the chaos increases exponentially with team size. We referred to the parable of the blind people and the elephant in a previous article. It’s a metaphor for how different people with incomplete information can perceive the same thing differently.
The closer something is to development, the more you want people to understand it well - you want to see the elephant clearly. You know my bias. Leaving this understanding to verbal communication is not just inefficient, it also leaves room for misunderstanding. Asynchronous methods can not just help convey this information at speed, you also allow the communication to get better with time. Let’s explore some ways you can do this.
1. Idea papers
Credit where it’s due. I didn’t have a name for this before I read Effective remote work, by James Stanier. In my teams, we’d just have a generic, unimaginative name for it. You know, something as boring as “shared document”. I like the term “idea paper” much better. It’s as straightforward as it sounds. It all starts with an idea. The trigger could be something internal, such as a clunky framework that’s causing developers a world of pain. It could also be something external, such as usage data for your product or an insight from competitor analysis. If you believe you have a way to solve a problem for your team or your stakeholders, write it up!
New ideas are fragile. They need care and nurturing. You need to develop them without the pressure to explain them with charisma, in a room (or Zoom) full of people. When you take the time to write it up, you can make all of your assumptions explicit.
You can enrich it with data and illustrate it if you have to.
Do you expect questions? Add an FAQ!
Are you clear about how to implement it? Throw in some implementation details.
It doesn’t have to be long. In fact, I suggest you make your idea paper easy to scan and as crisp as possible. Once you write things up, people have the chance to read one consistent version of it. None of that blind people and the elephant stuff.
If they have feedback; they add in a comment. You respond and strengthen the idea.
When they have questions, they ask inline. You can then enrich the FAQ.
By the end of a round of feedback, your colleagues have inspected your idea and you’ve had the chance to enrich it. When everyone has the same information, it also facilitates decisions - especially if the team needs to agree to implement the idea.
As I say this, I must share what I think is the team’s responsibility when reading an idea paper. The fine folks at Basecamp say it much better than I ever will.
It doesn’t have to be crazy at work - Basecamp
“We don’t want reactions. We don’t want first impressions. We don’t want knee-jerks. We want considered feedback. Read it over. Read it twice, three times even. Sleep on it. Take your time to gather and present your thoughts—just like the person who pitched the original idea took their time to gather and present theirs. That’s how you go deep on an idea.”
You’re better off slowing down this process than trying to rush through it. As we’ve discussed earlier, speed and productivity aren’t the same thing. If you take the time to let an idea develop, you get the payoff when you deliver it at speed.
2. Feature breakdown documents
Business analysts, product managers and product owners usually work a few sprints or weeks ahead of the team to define the mechanics of certain features or system capabilities. Feature breakdown documents are a great tool to align the team on all aspects of implementation - from the business context, to the details. Fear not - this isn’t a long systemic requirement specification from the days of yore. Effective feature breakdown docs are brief and help connect various artefacts. They don’t serve as product documentation. Instead, they’re a reference for the development team. Here’s what I include in my feature docs.
Business context and success metrics, if any.
A brief explanation of how it’ll work.
Links to any of the applicable artefacts.
Research about end users and feedback, if any.
Mockups or wireframes.
User stories and epics that this feature relates to.
A list of frequently asked questions. You can create this as you get reactions from people.
Confluence has a fabulous template for this, and while I don’t use every single section in it, I think it’s a useful starting point. The reason feature documents are powerful is that you can enrich them as you go. Often we build the minimal version of a feature and wait for feedback to enhance it. When you get that feedback, guess where you link it up? The feature doc! What about new user stories - where do you reference them? Course, the feature doc. How about known issues? No brainer, eh? Use them well, and the document can be a powerful, single source of truth to describe the lifecycle of a feature or system capability.
3. Technical design documents
The technical counterpart to functional, feature documents are “design docs”. If architectural decision records (ADRs) are the summary, design docs are often the detail that lead to that summary. Much like idea papers, design docs allow the team to slow things down and articulate various design aspects of architecture and software solutions. The team can use the design doc as the working artefact to refine their thinking, respond to each other’s feedback, and build consensus. And finally, when the design process is complete, someone in the team can log the ADR as a summary of the process. Depending on the design decision you’re taking, it can include several details - scope, goals, system context diagrams, API descriptions, cross functional requirements, data storage, etc. I leave it to you to check out the guide, but I want to give you a heads up.
Industrial Empathy
“Design docs should be sufficiently detailed but short enough to actually be read by busy people. The sweet spot for a larger project seems to be around 10-20ish pages. If you get way beyond that, it might make sense to split up the problem into more manageable sub problems. It should also be noted that it is absolutely possible to write a 1-3 page ‘mini design doc’.”
Good design documents need detail. Even if you don’t write them down, the details are out there. By not writing them, you play a game of Chinese whispers, where everyone has a different interpretation of the details. The broader the impact of the design you’re proposing and the larger the team, the more misinterpretations will hurt you. So get into the details and take the time to read the details.
As team size increases, communication becomes more complex. Small teams will eventually bring in new people. Such is life. Team size aside, you’ll find that complex decisions lend themselves better to the written word. Moreover, there are limits to what people can remember, so it makes sense to commit things to writing. So keep calm, slow down and write the docs! Once you see how they help you drive consensus and shared understanding, you won’t look back.