Knowledge-Sharing with Design Docs

design doc, shift, code

Shift’s engineering team has always had an informal process around design docs for new systems, but the process has varied from team to team and engineer to engineer. We’ve had the assumption that if a project or feature is expected to take more than a week or involve more than one engineer, it probably makes sense to document your design in advance so you can get feedback.

A few engineers from our infrastructure team recently formalized the process to add some consistency with the main goal of streamlining the process–we want the term “design doc” to mean the same thing to everyone and to prevent engineers from feeling like they have to reinvent the wheel every time. We also think design docs can be used for mentorship because they allow junior engineers to get feedback faster than through code reviews.

As we thought about what we wanted from the process, we wanted to make sure the process made sense for Shift. We have a medium-sized engineering team, project teams are colocated, and most systems are built from a small set of common infrastructure. With that in mind, we wanted a process that was:

  • Low overhead We wanted the process to be a forcing function to make sure the right conversations happen while incurring as little overhead for the author as possible.
  • Focused on readability It was important that the progress naturally encouraged authors to write documents that were comprehensible to readers who likely had less context than engineers directly on the project team. One way we accomplish this is by encouraging authors to focus on examples rather than formal specifications–a format which we intend to be easier for both the author and the reader.

Here’s what we settled on for a typical process:

Shift design docs have three reviewer roles. The same person can fulfill more than one role, but ideally there is a minimum of two reviewers with at least one being outside the team to help spread knowledge:

  • Domain The domain reviewer is an engineer who’s familiar with the code and problem domain. Their job is to provide detailed feedback about whether the design meets the stated goals, whether the design aligns with the overall direction of the code area, whether there are better alternatives, etc. Since the domain reviewer is closest to the specifics of the situation, they’d ideally provide the bulk of the feedback.
  • Engineering manager The engineering manager for the project also reviews the document to help with cross-team coordination, which can include things like aligning or removing dependencies between projects and calling out scope creep. Ideally, the engineering manager wouldn’t have many comments on the design itself beyond what the domain reviewer added.
  • Architecture Someone from the infrastructure team reviews with a focus on questions such as whether common infrastructure is used appropriately, whether the design follows best practices on security and privacy, or will the design be easy to debug if it’s involved in a production outage at 3am. The knowledge transfer also goes in the other direction: the infrastructure team can use design docs to understand common needs from application teams to help prioritize further development of standard components.

The workflow is typically an iterative process–especially during the early stages when the solution space is being explored. It usually goes something like this:

  • Problem statement + Constraints The author starts the doc by researching and articulating the goals of the project and the known constraints. The author should also have an opinion about what solution they want to pursue, but doesn’t need to spend time documenting them in detail.
  • Whiteboard Session The author and the domain reviewer meet and sketch out potential solutions on a whiteboard. The goal is to pressure test the ideas beforehand as thoroughly as possible and to understand what the alternatives are.
    Once the author and domain reviewer agree on a solution, the author drafts a high-level description of the design. We have a strong bias for readability here–this means concrete examples over complete specifications or schemas. Obviously, the author will need to understand the formal specification to implement it correctly, but concrete examples are a better mechanism for helping reviewers understand the solution at a glance.
  • Alternatives It’s frequently helpful for the author to include the alternatives they considered so the reviewers can get a more complete view of the solution space. It also helps future readers understand whether the solution proposed in the doc applies more generally or whether other alternatives are appropriate for different contexts.
  • Anything else Based on the feedback the author is looking for and their overall familiarity with Shift’s systems, they may add any number of additional sections. This can include things like detailed designs (schemas, wire formats, system invariants), forwards and backwards compatibility concerns, rollout plans, and even proposed milestones.

We’ve been using this new process for a little under two months and have been getting a lot of value out of it. Junior engineers have gone into much more detail about API than initially intended, and that’s okay. Other folks have used an abbreviated process (define constraints, whiteboard, document) to talk through strategic technical decisions without necessarily looking for a full set of approvers.

One of the most exciting things about working at Shift is the ability to see an engineering team grow. As we increase in size, we want to stay true to our values of tackling hard problems (which we call “Building The Differential”) and betting on each other. Interested in learning more? We’re hiring!