Menu

Subscribe

Architecture Jams: a Collaborative Way of Designing Software

Software is rarely designed in isolation. It doesn't happen by one person going away in their corner for some time, then coming back with a thoroughly thought-out map of what to build and how. And as they explain the approach, the rest of the team nods, then everyone follows this master plan to build the system.

Instead, what actually happens in productive environments is one of the engineers makes a proposal, mapping out their thinking of how to solve the problem. This starts a discussion, and others join in. These others might be people who will work on the project or people with relevant domain knowledge. Usually, a lively debate continues, with people bringing up edge cases. Some people playing devil's advocate and others stress test the design. On the way, modifications might be made, to the point that all people with interest in the project are happy. After the group agrees, some more feedback might be gathered by an RFC-like process, and then the team starts building.

It's a good idea to facilitate an architecture jam early on in the design process, instead of letting it play out organically, over a longer period of time. Doing so will mean more immediate feedback, a lot more people invested in the idea and blind spots of the approach caught earlier.

Most successful projects I've seen from rebuilding Uber's payments systems to building Skype for the Web all started as an architecture jam. Of course, eventually these massive projects broke up to multiple streams, with their own architecture jams. Some were more, and some less efficient. Here are approaches I've seen good architecture jams follow, over the years.

  • Be mindful of who you invite. You want people in the room who will be giving feedback or contributing. It can also be a good idea to include a more junior person as part of getting them exposed on how these sessions go as part of good mentorship: just make sure you'll encourage them to contribute during this session.
  • Start with the goal of the project. As tempting jump straight into boxes and arrows, don't forget that architecture is just a tool to get things done. Make sure the whole room is on the same page on what problem you'll solve.
  • Lay out constraints and principles that need to be accounted for. Many back-and-forth discussions tend to happen when participants optimize for different things. An engineer might draft a design where they optimize for latency and horizontal scaling - when another engineer might be optimizing for touching the fewest systems possible. Unless the constraints and priorities are not made explicit, people can talk past each other until they finally realize that they are aiming at different targets.
  • Use a (virtual) whiteboard, if you can. Whiteboards have lots of benefits in collaboration: it's easy to draw out thoughts. It's also easy for others to collaborate. When you're sitting remote, it's more tricky: but shared drawing tools where anyone can take the lead and sketch their ideas make a difference.
  • Present your proposal. Keep it casual, aiming to spark discussion, and get feedback. On-the-spot drawing on a whiteboard is a great way to do so. Having a slide deck might be too formal in some cases, but can work in others.
  • Step back and give space to others. Encourage people to share their thoughts and feedback. If you're doing whiteboarding, give the markers to others so they can visualize their ideas. If you have that more junior person, make sure they also give their take.
  • Facilitate the meeting, ensuring the discussion progresses towards the goal of coming up with a reliable approach. Good facilitation takes practice: you might need to table some unrelated discussions and use questions, perhaps lay out constraints to keep moving.
  • Commit after addressing disagreements. Aim for an approach that people are willing to commit to, even if they might not agree with it.
  • Close with a clear outcome. Either you'll all be violently agreeing on an approach, or there will be no agreement on some key areas. Not agreeing is okay and more common than you'd think. In this case, decide on actions to take to settle key loose ends: perhaps with a smaller group. When that follow-up discussion is done, that should leave you with a plan that everyone can commit to.
  • Summarize with notes. Collect the key decisions made and write up the summary, circulating it back to the meeting attendees. If you used a whiteboard, take a photo and either attach this or convert it to an editable diagram. Assuming there was an agreement, these notes might be the start of the design document.

Finally, have a plan on getting the results to production. Architecture done for the sake of architecture is a poor investment. You'll want to solve an actual problem, ship this as a solution and confirm that it works and improves things. Perhaps this is straightforward, as you're already building the project. If not, are you creating a prototype or an MVP? You have an agreement - so get down to coding, releasing, and validating the architecture.

Featured Pragmatic Engineer Jobs

  1. Senior Backend Engineer - C#/.NET at Straddle. £90-125K + founding team equity. Remote (UK).
  2. Senior Solutions Engineer at Tint. $130-195K. Remote (US).
  3. Product Engineer at Causal. Remote (US, UK). The team tackles interesting challenges like simplifying React state management.
  4. Backend Engineer - Data at Causal. Remote (US, UK).
  5. Senior Backend Engineer at Polarsteps. Amsterdam (Netherlands).
  6. Senior Data Engineer at GetHarley. £70-100K. Remote (UK) or Hybrid.
  7. Senior Frontend Engineer at GetHarley. £70-100K. Remote (UK) or Hybrid.
  8. Senior Software Engineer at Tint. $140-195K. Remote (US).
  9. Senior Product Engineer, Frontend at Attio. £90-125K + equity. Remote (Europe).
  10. Senior Data Engineer (RoR) at Terminal49. $140-200K. Berkeley, California.
  11. Engineering Manager - Security Product team at CAST AI. Remote (Lithuania).
  12. Software Engineer at Freshpaint. $130-210K + equity. Remote (US).

The above jobs score at least 10/12 on The Pragmatic Engineer Test. Browse more senior engineer and engineering leadership roles with great engineering cultures, or add your own on The Pragmatic Engineer Job board and apply to join The Pragmatic Engineer Talent Collective.

Want to get interesting opportunities from vetted tech companies? Sign up to The Pragmatic Engineer Talent Collective and get sent great opportunities - similar to the ones below without any obligation. You can be public or anonymous, and I’ll be curating the list of companies and people.

Are you hiring senior+ engineers or engineering managers? Apply to join The Pragmatic Engineer Talent Collective to contact world-class senior and above engineers and engineering managers/directors. Get vetted drops twice a month, from software engineers - full-stack, backend, mobile, frontend, data, ML - and managers currently working at Big Tech, high-growth startups, and places with strong engineering cultures. Apply here.