Working with design papers

Even when we were not all working remotely we had them, but remote work has made the use of design papers to prepare, discuss and structure major engineering initiatives even more useful.

This is a brief overview of the approach, from a simple one to a very structured one.

This post was originally published on our parent company's blog: https://blog.imfiny.com/working-with-design-papers/

The concept

We are talking about the writing of a document explaining how a new large feature, a large change or a new service is going to be implemented.

But the writing of the first version of the document is just the start. It's followed by rounds of comments and discussions to make new versions of the document until a certain state of approval has been reached.

That document then serves as basis to follow to build the new system. In the best case, once the system is built a retrospective should happen to compare what was expected and how it went.

The reasoning behind this is that while someone can come up with a great idea it's great to have other people in the team review, comment and help that idea be really great.

Those papers are usually written by technical leads among the team, but senior engineers, being the next leads, can also come up with proposal and take part in the exercise.

A minimal approach first

Some call those papers "RFC", reusing the acronym used by the IETF for its "Request For Comments" papers. Unlike those they are not set in stone though and are meant to be, well, commented.

The base idea is for the author(s) to describe a situation ("here is what's not working right"), compare it to how the current industry usually tackle these kind of problems (research and state of the art), and then describe how that approach can be used to solve the identified problem.

This can be done through a Git repository hosting all the RFCs, with each new proposal being pushed first in a branch opening the way to a discussion through a pull request review process.

Technical leads and senior engineers can then chip in, and the process will make new revisions of the document happen until either deadlocks appear or an agreement surfaces.

This process works nicely with asynchronous communication steps but live meetings should happen at different steps, either to help remove deadlocks, to discuss specific points or to conclude on the document.

It should be clear in the team who will be final judge though. Usually those documents are brought to the attention of all the leads for discussion and review but the CTO, a specific Technical Lead should be considered as the one who will validate the proposal and have the final word on the review.

A more structured approach

The process is actually called Technical Design Review in many places and is not specific to the software engineering world.

A quick search reveals many articles on the topic :

• https://medium.com/caspertechteam/rfcs-lightweight-technical-designs-a508d93ccd34
• https://medium.com/git-out-the-vote/strengthening-products-and-teams-with-technical-design-reviews-ae6a1bec5216
• https://www.smartsheet.com/content/design-review-process
• https://www.managersresourcehandbook.com/overview-technical-design-reviews/

The latter two especially referencing more industrial processes with the heaviness that it might convey.

Yet, this can be usefull to read and know about to understand the reasonning behind such an approach to prepare, lead and implement important changes within a product and its stack.

To conclude

RFCs, TDRs are great ways to prepare the grounds for big and massive work pieces, doing the due diligence, so that the amount of surprises is reduced. This also helps with knowing about alternative approaches and be ready to alter course when things don't go as planned.

It might seem odd to some people to see this concept. It does sound like planning a lot before going into battle. That might sound like a waterfall approach. But this is not so much about building a "grand plan" for the next 3 years. Rather, it's a way to figure out what's next and prepare how we are going to do it. As the design paper is prepared and reviewed, authors and reviewers should keep in mind the scope of the document should probably be limited to some extent to avoid falling into such a blind approach to the future.