Table of contents

Shortly after I joined my current team, I realised there was something wrong with the way the features were being designed and later implemented.

🚨 Since all the knowledge was transmitted verbally, a responsible engineer was a single point of failure. If that engineer got suddenly sick, the work could be at risk of being seriously derailed.

❌ If a feature got deprioritized, and later resumed, it caused noticeable disarray in the development flow, because after a month or two nobody could remember where the things were left off.

👻 There were parts of the application that were so ancient, that nobody knew how exactly they functioned and why were written they way they were, because the people who built it already left the company.

😱 In worst cases parts of the feature in development done by two engineers could not work together, since the development wasn't properly aligned since the beginning.

Clearly, something had to be done.

# The solution

This is where I came up with a set of measures that seemed to be the right solution.

✅ First thing off, for every feature an engineer is chosen, who will be in charge of the implementation.

✅ That engineer is in charge of writing a design document (some call it "RFC").

✅ The document is being written during the discovery and design phases and later groomed in the iterative manner.

✅ The document is treated as a living thing, which means it must be updated should something be changed.

✅ The engineer must be in contact with the stakeholders and keep the team in a loop.

✅ If the engineer is sick or leaves the company for good, the work could be easily taken over by some other engineer.

✅ Should the feature be put on hold, there is a clear way to resume it later.

# The document structure

The design doc typically has a certain structure, which contains, but is not limited to, the following sections:

👉Title that clearly states the subject of the document.

👉Header that holds the name of the responsible, the deadline and the status of the feature.

👉List of stakeholders, including names, the approval status and the flag whether the review is required or not.

👉Link to the Slack channel, where the discussion is taking place.

👉Optional glossary, just in case there are some acronyms referenced in the document and needed deciphering.

👉Description of the feature/problem and its purpose.

👉Key provisions that are given as a must-have for the feature to be implemented.

👉Overview of potential solutions with pro-s and con-s. Usually it makes sense to have at least two option to choose from.

👉Chosen solution with reasoning.

👉List of affected downstream features/services, if any. Each item should contain explanations about what is exactly affected, a link to a design doc from their end, and a full name of a contact person of that project.

👉Section about technical implementation, including all the necessary details.

👉Risks section, including all the possible risks and their mitigation strategy.

👉Milestones section that holds the list of tickets grouped into deliverable buckets.

👉A list of references to the sources and other important documents.

Here is the template for a sample design doc, feel free to use.