Distinguishing Between Design Documents and Architecture Records
Both are necessary and helpful, you just need to know when to use them.
👋 Hi, this is Thomas. Welcome to a new edition of Beyond Runtime, where I dive into the messy, fascinating world of distributed systems, debugging, AI, and system design. All through the lens of a CTO with 20+ years in the backend trenches.
QUOTE OF THE WEEK:
“Documentation is one of the most important parts of a software project. However, a lot of projects have little or no documentation to help their (potential) users use the software” - Eric Holscher, co-founder of Write the Docs.
As Eric Holscher says, effective software documents play a pivotal role in successful application development. They bridge the gap between concept and implementation, ensuring all stakeholders share a unified vision of the project's goals and execution strategy.
Two types of documents are particularly helpful: software design documents (SDDs) and architectural decision records (ADRs).
However, while both play vital roles in software development, they serve distinct purposes and address different needs within a project's lifecycle.
Software Design Documents: the complete blueprint
SDDs function as comprehensive project guides, created during the initial planning phases when requirements are clear but development hasn't begun. These documents cover:
System architecture and overall structure
User interface specifications
Database design plans
Security protocols
Performance requirements
Deployment strategies
Their primary purpose is to align all stakeholders on the project's direction before committing resources to development. They serve as a reference point for both technical and non-technical team members, ensuring everyone understands the project's scope and objectives.
Architectural Decision Records: the technical history
ADRs take a more focused approach, specifically documenting the evolution of technical architecture decisions. These living documents track:
Major architectural choices
Technical constraints considered
Alternative options evaluated
Reasoning behind final decisions
Impact analysis of architectural changes
Their primary audience consists of developers, architects, and technical team members who need to understand why the system architecture evolved in specific ways.
Working together
Rather than competing documents, SDDs and ADRs complement each other in several ways:
SDDs provide the broad vision while ADRs detail specific technical decisions
SDDs reference relevant ADRs for detailed architectural context
ADRs support and explain the architectural choices outlined in SDDs
Both documents evolve as the system grows and changes
Organizations benefit most when they maintain both types of documentation, using them in tandem to provide a complete picture of their software systems. This dual approach ensures that both high-level project goals and detailed technical decisions are properly documented and accessible to all relevant stakeholders.
💜 This newsletter is sponsored by Multiplayer.app.
Full stack session recording. End-to-end visibility in a single click.
I originally wrote about this topic in this article:
I explored these topics:
Why software design documents are important
Software design documents vs. architectural decision records
Core elements of a software design document
Software design document template examples
Best practices for writing software design documents
📚 Interesting Articles & Resources
Practical OpenAPI in Go -
This article explores how OpenAPI can streamline API development in Go by providing a structured, language-agnostic approach. It covers the benefits of defining APIs using openapi.yaml, generating Go server code from the specification, and integrating it into projects for consistency and maintainability. By adopting a design-first methodology, teams can improve collaboration, enforce standards, and simplify API implementation.
Why is dbt so popular? -
dbt (data build tool) has gained traction because it enables SQL-based data transformations while promoting software engineering best practices. It allows teams to version-control transformation scripts, generate automatic documentation, and implement data testing, making data workflows more reliable and scalable. By treating data transformation as code, dbt bridges the gap between data analysts and engineers, streamlining data modeling in modern analytics stacks.
Diagram-as-code tools are just a step towards the tools we need - Vladi Stevanovic
In this article, the author discusses the evolution of system architecture visualization tools from Diagram-as-Code (DaC) tools like Mermaid and PlantUML to newer interactive tools that provide real-time, continuously updated views of system architectures.
Great write-up and thanks for the mention!