Key Design Decisions

Key Design Decisions

By 28 October 2020Planning, Technology

Key Design Decision Documents help record important thought processes for communicating with future team members.

 

When I suggested writing a blog about Key Design Decision documents my fellow architects were initially unimpressed. “Surely EVERYONE knows about KDDs”.  

That has not been my experience. I think they are a very useful tool for communicating some high level concepts between senior management (including product owners and project managers) and the engineers on the ground making a system work. A quick discussion may be fine for everyone currently on the project and all the stake holders. However, anyone who joins the project later on may not understand why the design is the way it is and may diverge from that design without even realising it. At best this may result in wasted work. At worst this may result in conflicting systems. 

I am thinking of technological decisions but that is not always the case for every project. 

KDDs are now one of the first documents I create when joining any project, even if I was not the one to make the decisions. It helps to document my understanding of what is going on and if nothing else prompts discussion 

The Agile software development methodology tries to avoid any unnecessary documentation tasks. It calls unnecessary processes “smells” but this is anything but smelly.  

Format and content 

So what is the format of a Key Design Decision? It turns out there is no universal format, and it almost doesn’t matter what you choose. You could put everything in one document, or have separate files or directories for each decision. It depends on how much detail is appropriate. I would suggest that you might spend more time on the contentious decisions rather than treating it as a text box exercise. Here are some of the things you might want to include: 

  • A simple sentence describing the decision to act as a human readable name.  
  • A unique identifying number. That is always wise so that it can be referenced easily elsewhere. (That hints at a spreadsheet or database rather than Word docs, but doing it manually will be fine) 
  • More explanation of the decision made 
  • The reason for the decision made 
  • A date the decision was made 
  • Who made the decision 
  • The problem or question that the decision is meant to answer   
  • The alternatives that were considered and why they were rejected 
  • The risk if your decision is wrong  
  • The effort required to change the decision later on 
  • The implications of the decision 

Templates 

A swift google search reveals a bunch of possible templates for free. I would not worry about getting the most perfect template. Figure out what will actually get used by your team.  

Conclusion 

So KDDs are pretty simple documents and they don’t have to be created by an architect. Any project manager or senior software engineer can start them, and could also keep them up to date. There are lots of benefits if you are working in a team. 

References 

For more reading these articles talk about Key Design Decisions, though they are often called Architectural Design Decisions.  

Photo of a signpost from Hadyn Cutler on Unsplash

Author

Alex McLintock has over 25 years in the IT industry. Alex runs Alephant which helps companies in London to design new systems for Big Data Analytics and Data Science. He has written several articles here.