A new engineer will change the code and break something because they don’t know the context that came before; engineers will overlap, working on similar problems without realizing it; and significant time will be wasted.

Heading into the Wilderness

Most engineering teams rely on design documents to describe, scope, and approve projects or features. Those aren’t new in and of themselves (they're just the foundation of what we'll talk about here). Kicking off a project without one would be like a hiker heading into the forest without a map. Engineering teams don’t have that kind of time. For those who are new to the concept, here’s a good example of one.

Design docs are helpful for a variety of reasons:

Alignment: As a team gets bigger and starts working on multiple facets of a product, the right hand stops knowing everything the left hand is doing. Code and systems can conflict if people aren’t able to understand everything that’s going on. Design docs serve as a single place that can be discussed, consulted and understood team-wide.

Critical context: If catalogued historically, they can be the best way for new engineers to get up to speed on why a product or feature was built, why it operates a certain way, what experiments were tried, and why certain decisions were made. They can memorialize the choices of employees who may no longer be at your company.


Making tradeoffs: “Everything from optimization of a system to new features requires tradeoffs,” Parham explains. “Maybe you need to save time, or people, or launch earlier than you’d otherwise want and have to accept tech debt to pull it off.” If you record your tradeoffs, you put a stake in the ground that makes your team’s priorities clear. Then, when circumstances change, it’s easy to go back and review whether you need to keep making the same tradeoffs.


Design Docs That Work

In practice, creating these documents can become a bit of a hot potato — often, no one wants to take the reigns of authoring one of these things. It can seem onerous, time-intensive, distracting from the code. And at many companies, they’re written up and sent out only to receive resounding silence from the rest of team.

“People will send out a design doc in an email thread and ask everyone for feedback,” Parham - former Deputy CTO for Hillary Clinton’s presidential campaign says. “Then you get this game theory problem where everyone thinks that someone else is going to read it and give feedback, so no one does."

"Let your junior engineers write the original design doc and then the senior engineers act as editors,” he says. “It helps with team dynamics by empowering engineers and frees up time for your senior engineers."Engineers will only put in the work if they know it’s going to be properly reviewed by the whole team."

Your document should not just be a collection of ideas explained in writing, but actually have distinct sections (consider it a checklist), including:

Background: Background on the problem you're solving. Why does it need to be solved? What other systems, features or products touch it? Who should be involved throughout?

Design goals: Requirements and goals of the project. This should also include numbers like traffic assumptions, usage, uptime requirements, etc.

System diagram: Diagram of all the binaries, databases and third-party services that this design touches. Having a visual helps many folks get the high-level picture and understand what's being impacted a lot more easily.

Design summary: Summary of the solution in a paragraph or two. This should not go on too long; it’s meant to paint a quickly and easily accessible picture of what’s being built.

Design details: Where the actual specifics of the design are listed out. This can include a variety of things from detailing subcomponents, code locations, testing strategies, internationalization, scaling tactics, etc.

Tradeoffs made: This is a great place for disclaimers on why certain choices are being made, what any negative implications might look like, limitations being taken into account, any technical debt that might be earned along the way, and changes that may need to be made in the future as a result.


Set Ground Rules

Once you have a solid design document in place, it’s time to prepare for the review itself. But how do you conduct an in-person review with that many people effectively? 

First, choose a moderator and note taker for your session. They should be neutral parties with no emotional stake in what you're presenting. Then email the group you want feedback from at least 48 hours before the in-person review is scheduled. Send out the design doc along with the blank Google doc for questions and comments. In that email, set ground rules and expectations for the meeting. He suggests sending your team this list of guidelines in order to ensure a productive session:

Everyone should add questions to the Questions doc before the meeting. This doc will be the agenda of the review and allows us to optimize for people’s time by diving straight into the issues. Please add your name next to the question when you add it.

Everyone is welcome to sit and listen, but there's no talking in the meeting unless you’ve read the design doc. The moderator will jump in and cut off questions if the answer is in the doc. 

No email and no typing except for the note taker. Feel free to have your laptops open, but only to read the design doc. We're here to give the next 45 minutes to this product/feature with all of our attention. You'll appreciate people doing the same for you when you present a design doc in the future.

The moderator will keep things moving and might ask for specific discussions to be followed up offline. Again, this is to make the most of the group's time. Hold non-on-topic questions until the end, but feel free to jump in with any questions that pertain to the current discussion. The note taker will try to capture everything.

90% of the team will probably ignore the email at first because they’re busy with other work. But if they get a chance to read the doc, they’ll definitely have questions to add (no design doc is perfect).


Force Focus

The day of the review, you want to stay organized and keep everyone focused for the full 45 minutes allotted. The only way to do that is to create an agenda and stick to it. Here are the steps to ensure you run a successful in-person design review:

1. Send a reminder.

A few hours before the review starts, send another email reminding the team to add their questions to the specified doc. Typically, this is when most people will actually read it and contribute. Then, about 30 minutes before the review starts, the moderator should go through the questions and batch them according to context.

In order to make sure the right people participate and actually come to the meeting, you may have to get a little creative. Everyone will have their own methods, but the commonality has to be energy. You should be pumped for this occasion. Make it clear it’s important to you, to your team. You’re excited to get feedback so you build the best thing possible. Use whatever tools you have at your disposal to relay this excitement.

“At Google, I would use Nerf weapons to get everyone to go to the design review,” Parham says. “We would just fire at them until they got up and went. I would run around the hallway and say, ‘Design review time! Design review time!’ You can use food, turn off their email accounts, whatever you need to do to get people in there.”

2. Review the rules.

To kick things off, the moderator should remind the note taker to keep track of key points and insights during the review. With everyone in the room, they should briefly run through the rules to enforce them yet again.

“Emphasize that you shouldn't talk unless you've read the design doc,” Parham said. “This is key because in many design reviews, people who haven’t read the doc will start asking questions that are in there already and have already been answered. It wastes everyone's time. With maybe 20 people in a room, you need to be super efficient. Engineers really appreciate it when their time is respected.”

After you read the rules, a bunch of people will pull up their laptops, open the design doc and start reading it. “People normally go to meetings and just listen, but if you tell them they can't actually provide input unless they do this thing, they'll read it.”

3. Have each person read their question aloud.

During the design review itself, the presenters shouldn’t just go through the questions as you might expect. Instead, the person who wrote the question should ask it themselves.

“Have a human ask the question to the team presenting the design in order to prompt more human answers,” Parham says. “That elicits real, more authentic discussion. If you have someone both read and answer a question one right after the other, they’re more likely to be dismissive, not fully understand the question, and not provide a satisfying answer.”

Push through all the questions this way, with the moderator interrupting if any given contribution goes on too long, and with the note taker documenting any changes or decisions made. Ideally, the note taker writes everything down within the Google Doc that listed all the questions, so you can keep tabs on whose questions got answered and how. This will make the notes easier to parse for everyone after the fact as well — especially those who were not in the room, but who are interested in the project. You can see an example of a filled-in questions doc here.

“If you did a good job on the design doc, there shouldn't actually be that many big broad unanswered questions,” Parham says. “90% of questions will require a very straightforward answer. It could be, ‘Oh, we didn't put that in. Here's the trade-off we made. Here's why. We will add it to the doc, etc.’”

4. Open up the discussion.

Once you’re done reviewing the full list of written questions in the Google Doc, the moderator should open up the discussion to the whole room to ask and answer any other ad hoc questions that come up or provide feedback (if there’s time). Ideally, there shouldn’t be a ton of edits, but there may be.

“At Google, if the design doc clearly had a bunch of issues that people highlighted in the discussion, we'd ask them to come back for a second round with updated changes,” Parham says. “This only applies to large teams, maybe a 100+, where it was really important for everyone to be clear on the details. Then it was okay to go spend a week and get it right, because you might be building a system that has to last for years.”

This is exactly what happened when his team was designing the Google Apps Marketplace a few years ago.

“I remember the design doc went through multiple iterations because it was such a massive project,” he says. “Marketplace was one of our first early remote teams, so there were a bunch of communication breakdowns. The design review process helped with that because we only spent a couple of weeks going back and forth instead of building a system for six months and then launching it only to realize it wouldn’t work, or would break a bunch of other things, or didn’t meet people’s expectations.”

In fact, this type of design review is particularly useful for large teams and those that have a lot of remote workers, he says. Often times, remote workers feel left out of discussions that happen at headquarters, so this process empowers them to learn about everything that's being worked on by the team and have their voices heard.






At IBI Global, we believe that education drives technology not technology drives education since good teachers and experts inspire learners to be lifelong learners.



       IBI Global_EdTech Awards_2020_Finalist