Technical design docs

The technical counterpart to functional, feature documents are “design docs”. If architectural decision records (ADRs) are the summary, design docs are often the detail that lead to that summary. Much like idea papers, design docs allow the team to slow things down and articulate various design aspects of architecture and software solutions. The team can use the design doc as the working artefact to refine their thinking, respond to each other’s feedback, and build consensus. And finally, when the design process is complete, someone in the team can log the ADR as a summary of the process. Depending on the design decision you’re taking, it can include several details - scope, goals, system context diagrams, API descriptions, cross functional requirements, data storage, etc. I leave it to you to check out the guide for more details.

Be aware that good design documents need detail. Even if you don’t write them down, the details are out there. By not writing them, you play a game of Chinese whispers, where everyone has a different interpretation of the details. The broader the impact of the design you’re proposing and the larger the team, the more misinterpretations will hurt you. So get into the details and take the time to read the details.