Strengthening Products and Teams with Technical Design Reviews
An engineer’s time is one of the most precious assets of a tech team no matter where you are. While I was at Google, one of the places a lot of time went into was the process of designing new systems. Design docs would be written, however not always read by the majority of the team since it was blasted out without mechanisms of having discussions about it. Alternatively if a meeting was held to discuss a new system, it often turned into a presentation about decisions already made instead of a discussion about them. After a lot of iteration tackling these issues, we developed a design review process that optimizes engineer’s time so that the most important design points are discussed as efficiently as possible. We use this process on the Hillary tech team since we have to move extremely quickly but it also provides other benefits like making sure all team members know what’s being worked on and onboarding new engineers faster.
As an example, the highly popular Trump Yourself tool was designed, reviewed, built and launched in under two weeks. In that time over 30 engineers participated in the design process with most spending less than an hour on it. Even with that little amount of time, a wide range of questions were highlighted and discussed about product, UX, operations, security and scaling issues. One major decision on how to structure the system was efficiently tackled by the process and a resolution was agreed upon in less than 15 minutes of senior engineers’ time. The product then went viral on launch day being hugely successful with over a million page views and scaled extremely well (hooray for well a designed product and tech stack!). In another Design Review for a voter protection tool, the discussion actually saved weeks of time since questions from the process led the team to go down a completely different path and avoid building an entire sub-system.
But it’s not just about saving time. The Design Review process helps with other challenges of an engineering team like:
- Inter-org communication. Often people don’t know what other folks are working on. With very large teams you might even have two different engineers working on the same problem and not realize it.
- Surfacing legacy work. Due to having design reviews, engineers can know that a particular technology problem had already been solved in the past.
- Onboarding new engineers. Always a challenge due to legacy systems but design docs and reviews create easily digestible documentation.
- Productive contribution. Design Reviews make it easy for a whole range of engineers to contribute thoughts towards a design. Often times little details are caught because someone with a different point of view jumps in. It also helps make it easier for shier engineers get involved due to the Questions Doc (detailed below)
Writing the design doc
The first thing the team needs to do is write the design doc (a base template is here). The document should have sections including:
- Background
- Design goals
- System diagram
- Design summary
- Design details
- Tradeoffs made
The doc should be written in a way that a new engineer can read and understand it. This process could take a couple days to a week and usually includes a number of conversations across teams. These conversations are the normal ones that occur while a project is being designed and the design doc then contains the result of those conversations. The document is ready when all the sections are filled in with enough detail that reviewers won’t have trivial questions.
Sending the technical design to the team for review
Once the design doc is written, it’s emailed to the whole team for review. Comments/questions should not be added to the document directly since often times discussions about larger questions are extremely difficult to do in a written format. That type of interaction is much better in person. To solve for this, a separate, blank Google doc is sent along with the design doc where questions are listed with names of people who asked them. These questions will become the agenda for the Design Review meeting. The email should be sent out a day or two before the actual design review to give everyone time to read through the design doc and add questions.
The Questions Doc
Now we have a Questions Doc with questions from all over the team. Fantastic questions can be broad like “Why did you choose to do X instead of Y” or specific ones like “Why aren’t you using library Z which this other team is using”. Often times these questions bring up issues the team has already considered, but bringing them up in a discussion format allows those explanations be dug into efficiently and directly. While the team could simply type responses in-line to these questions, doing this loses out on many benefits. Technical back-and-forth discussions can get complicated in written form and in-person discussions can spark other ideas. Having in-person discussions also allows junior engineers to listen and learn how senior engineers think about a problem plus shy personalities get a chance to have a louder voice due to only needing to add questions to a doc instead of speaking up in a big meeting. Both of these have the additional benefit of keeping team cliques from forming around the loudest or most experienced participants.
Short note: For super simple and non-debatable questions like “when is this launching”, answers are put directly into the Questions Doc to save time in the design review for deeper and more complex questions.
Design review meeting
The last step in the process is a Design Review meeting. This meeting is not a presentation. It is a place to have targeted technical discussions about a project. Time efficiency is top priority since you have many engineers all in the room and the explicit deadline of a meeting also helps make sure everyone reads the design doc and creates closure to the process.
We have found that a few rules are good to implement in this meeting:
- No typing except for the note taker
- Everyone is welcome to sit and listen but no talking in the meeting unless you’ve read the Design Doc
- Have a moderator who keeps things moving and can ask for specific discussions to be followed up on offline
These rules are really what make this process time efficient and work well. The moderator will cut off a question if it’s answered in the Design Doc or a debate goes too long which helps use everyone’s time effectively. The moderator needs to be almost ruthless in this process which can be awkward but it allows engineers to stay focused and know that their time isn’t wasted. The lack of working in the review also makes sure people take the process seriously and not zone out.
Lastly, a note taker documents the discussion in the Questions Doc. This pairing of a Design Doc and Questions Doc annotated with the in-person discussion is immensely helpful since engineers can later review what happened at a review even if they weren’t in the room. It also then becomes a resource to new engineers get up to speed faster since they can understand project history, different tradeoffs made and common design decisions of the team.
Ship it
Collaboration and communication makes for better designed systems along with stronger engineering teams. We have a framework now for providing feedback quickly and using minimal time from other engineers. This framework promotes collaboration and discussion before building and also provides extra visibility into the larger organization. It also allows junior or shy engineers to absorb and participate in discussions in a lightweight way so they develop into strong contributors. Plus you get some nice documents you can reference when people have questions later on. All these things grow a healthy team culture and promote the concept that projects are a team effort. Design Reviews do this all while keeping the time ask small. The campaign needs to move fast but so do most engineering teams so feel free to take this process and implement your own version!
