Blueprints at SendGrid

Note: This is engineering post. For more posts like this, check out our technical blog roll. 

Have you ever seen that project management cartoon about the tire swing?

Have you ever felt this hit a little too close to home? It’s a common problem as organizations grow. Even on a single team, not everyone has all of the context all of the time. The issue worsens as you need to work across teams, or across longer time horizons.

Product and Engineering teams at SendGrid use what we call “Blueprints” to help minimize the amount of drift in our projects, and ensure that we’re delivering what customers want. Blueprints consist of a single document that briefly states our shared understanding of the problem. The bulk of the document explains how we plan on solving that problem including:

• architecture design
• new APIs that are necessary
• sequence diagrams
• schemas for the data (where needed)

Because all of this lives in one document, the Blueprints provide a central place for interested parties to review and comment on the solution as a whole.

One of the biggest benefits of having a Blueprint is the framework it gives to engineering teams when they’re actually building the product. If there’s a decision to be made, referencing the Blueprint should help narrow the options or favor one option over others. In rare cases, it can even trigger a redesign of the solution in the Blueprint. As we work on projects that are longer than a sprint or projects that require multiple teams to implement, the Blueprint provides a useful compass to make sure all parties are working towards the same goal, and helps ensure a shared understanding of the goal.

The hidden gems of using blueprints

How many times have you hired a new engineer and showed her what you’ve already built, only for her to ask why you didn’t build it some other way?

It’s not enough to document how the system is built, but also why the system is built that way.

All Blueprints contain a section for “Other Considered Solutions.” This is where the engineers solving the problem can write down any other designs that were considered, and document the reasons they were not selected. Things like “Testing showed this solution didn’t meet the guarantees we need” or “This could solve the problem, but is considered too operationally complex” or “Purchasing a service to do this was considered too expensive” are important to write down.

If a new engineer starts and asks the question above, they can refer to this portion of the blueprint. One of three things normally happens:

1. The design they propose was considered and rejected due to the Blueprint creators having more context of the system as a whole.
2. Assumptions/Givens in the blueprint no longer hold true and should be revisited (especially true when designs are rejected due to cost or capabilities).
3. Their design is actually novel, and merits investigation.

Blueprints at SendGrid normally describe distributed systems. Since accepting tradeoffs is a hallmark of distributed systems, Blueprints are a convenient place to track the tradeoffs we’ve accepted in the proposed design, and why. For example, if the product values speed over durability, we’d likely choose an in-memory datastore over something that depends heavily on reading from disk. We’ll explicitly call out the tradeoff we’re making, with a short explanation of the limits that choice imposes. This helps Product understand the impact of say, choosing Memcached instead of MySQL for a given product.

In addition, Blueprints are updated as the product makes its way through to production and beyond, providing an “as-built” reference for the design. This is great for exposing new engineers to the design, history, and decision-making process behind those designs.

SendGrid Engineering trusts our Product organization to decide the right products for us to build, and Blueprints help make sure that we’re building them the right way. If you’re interested in working with Blueprints at SendGrid, we’ve got plenty of opportunities in Engineering we’d love to talk to you about. If you’d like to talk about Blueprints in your organization, hit me up on Twitter.