Rediscovering The Importance of System Design
By: Luiz Rolim
Tags: Engineering, Design, Architecture

In my recent experiences I started to adopt Design Docs as my de-facto way to build new functionalities. Here I’ll describe my personal take on such an approach highlighting the main benefits I have noticed as well as points that require some attention.

What is a Design Doc?

A design doc is a document which states the main design decisions around one piece of software serving as a piece of alignment. One initial point that I would like to highlight is that the concept of design decisions goes beyond architecture. It includes also things such as:

What is the background that required such a piece of software? What problems does it address ?

How to test the solution? How to monitor it?

Which kind of SLA impacts are we expecting, if any?

How to rollout the solution? Are there any communications that should happen?

What’s a suggested implementation breakdown ?

Last but not least, the bulk of it: what’s the architecture of the solution?

When to build a Design Doc ?

A second point that I would like to bring clarity lies in the definition of a piece of software, which might be large enough to accomodate from an entire system to a particular feature of that system. A natural question that follows-up lies then on the decision of whether a design doc is needed or not for a given feature. My opinion on that subject can be summarized by the following meme:

Of course we shouldn’t (usually!) build a whole design document to things such as:

A small UI change/tweak

One bug that needs to be addressed

A really small feature that can be shipped in a couple of days without much discussion

Even for seemingly small and harmless features though there are scenarios where we should consider building a design doc.

As an example, consider an internal api modification, like adding a new field on the payload, that could be likely implemented by the development team in just a few hours. However, what about the impacts that it would bring to the API clients ? Does it require a new version or not ? Is the chosen name well clear enough ? in other words: is it properly aligned?

Again I’m not advocating that one small chance such as the aforementioned example requires a design doc. The call should be based on the common sense and experience of the Tech Lead responsible for the implementation.

Alignment

Another very important benefit the design docs bring to the table is the alignment between multiple people around the decisions.

Another good practice that can be combined with design docs is a RFC (Request for Comments) approach, where several people, including the product team and external stakeholders are encouraged to comment and bring their concerns and suggestions.

Note that a RFC process is not really tied to Design Doc, since it might be used for all kinds of documents. Even this article was subject to a RFC process!

In theory, there’s no rocket science here: you just create a document, share it with a few people (or a bunch depending on the scope) and ask them to read it and place their comments. Then you reply to the comments and start threads until an agreement is made.Tools such as Google Docs and Atlassian’s Confluence easily allow for such workflow.

For an attentive reader, though, a few questions might arise here:

Which People should be included ?

For how long should we hold the implementation due to the RFC process?

In summary: How to fit the RFC process into an agile environment ?

While there are several possibilities, I’ll describe the approach I’ve used with my teams lately.

Design Docs & Agile

Here we’re trying to leverage an approach similar to what’s commonly used for Product Designers: to work ahead of the development team.

So, basically and conceptually, we want the TechLead of the team to create design docs for features that will be implemented on the next sprint. Once he’s done he would share it with the team and technical stakeholders and start the RFC process before a live-session and thorough refinement takes place.

When the time comes for the refinement the Design Doc is already reviewed and the main decisions are already anticipated, causing the refinement itself to be much faster.

Of course, during the refinement, some things would change because the TechLead wasn’t really able (or supposed) to come up with all the best possible solutions. But here, the important takeaway is that Pareto’s law should be considered: with just 20% of the effort (just the tech lead vs the entire team) is able to anticipate (at least) 80% of the decisions.

Some follow-up benefits that, perhaps, were not clear and are noteworthy:

The bulk of the team did not stop coding while the design doc was underway

Questions that relied on external stakeholders could be answered asynchronously (on a non-blocking thread ;) )

Pitfalls related to testing, monitoring, migration policies, etc, which usually would be left behind would now be at least properly exercised

It’s also important to highlight that the engagement of the team is crucial in the process, from the RFC stage until the live-session discussion during the refinement. First of all, the more people commenting and bringing concerns and suggestions to a given system design the better it tends to be. Furthermore, it reduces drastically the chances that members of the team would feel excluded, or with a sense of top-down decisions being made, which in turn would lead to all sorts of management issues.

It’s already a consensus that the role of a developer goes far beyond coding; product vision, communication, and leadership, to name a few, are as important as the technical skills.In that sense, creating design docs with increasing scope is an excellent way to assess the maturity and growth of a developer and, thus, it works as an useful tool for career management perspective:

You have a mid developer aiming for a promotion ? let him take part of a design doc. First in pair with a Senior dev; then, continuously let him coordinate design docs with increasing scope, assessing their quality.

Another interesting practice that is noteworthy is building the design docs in pairs, similarly to what is preached on the Agile Manifesto for coding. It brings excellent results as many common questions and answers, regardless of how experienced the tech lead is, might be anticipated by another set of eyes while still keeping the bulk of the team focused on coding.

Conclusion

Although I didn’t provide an example of a real design doc throughout this article there are plenty of resources that can be found online. Don’t use anything off the shelf, rather try to spend some time creating a template that suits the specific necessities of your organization.

As mentioned, try to cover especially the WHYS (background, known issues, questions) and HOWS (architecture, how to test, how to monitor, rollout) of a feature.

As an engineering manager it's important to drive your teams towards creating thoughtful documentation combining with them the standards that are expected and the cadence in which they need to be released. You should not usually be responsible for creating them. Rather, consider yourself as one of the stakeholders available to provide insights and reason about their several aspects. However it's really important to hold your team, especially the Tech Lead, accountable for the process.

To finalize, a few useful resources for those interested in knowing more

https://www.youtube.com/watch?v=aRPKBVHmm2U

https://www.youtube.com/watch?v=bgHL41e7vgI