Writing Effective SDDs – That Engineers Actually Read

The “Write-Only” Database Problem #

Most Solution Design Documents (SDDs) suffer from the same fate: they are written once to satisfy a manager, stored in Confluence/Notion, and never read again. Why? Because they are bloated with “Business Speak” and lack technical substance.

If your SDD is 40 pages long and starts with a 5-page “Executive Summary,” you have already lost your audience (the developers).

The Logic: An SDD is not a diary of your thoughts. It is a Contract. It is an agreement between Product and Engineering on what we are building, and more importantly, what we are NOT building.

The “One-Pager” Rule (The C4 Model) #

Your document must pass the “Scan Test.” An engineer should be able to scroll through it in 60 seconds and understand the system boundaries. To achieve this, do not start with text. Start with a Context Diagram.

We follow the C4 Model (Context, Containers, Components, Code). Your SDD needs to nail Level 1 (Context) and Level 2 (Containers).

The Anatomy of a Winning SDD #

Structure your document exactly like this. No fluff.

1. The Problem Statement (2 Sentences) #

• Bad: “We want to leverage synergies to optimize user acquisition.”
• Good: “Users currently wait 4 seconds for the dashboard to load because we query the legacy SQL API. We need to reduce this to < 500ms.”

2. The Context Diagram (The “Big Picture”) #

Before discussing database schemas, show how this system fits into the world.

• Who is the user?
• What external systems (Stripe, Twilio, Legacy Mainframe) do we touch?

C4Context
    title System Context Diagram - New Dashboard API

    %% 1. Actors (Top Level)
    Person(customer, "Customer", "A user of the web banking app")

    %% 2. The Boundary (Groups your new system components)
    System_Boundary(b1, "New Banking Infrastructure") {
        System(dashboard_api, "Dashboard API", "Aggregates account info")
        
        %% Note: Usually Databases/Caches are "Containers", but if you want them here:
        System_Ext(redis, "Redis Cache", "Stores recent transactions")
    }

    %% 3. External Systems (Outside the boundary)
    System_Ext(mainframe, "Core Banking", "Legacy SOAP Service (Slow)")

    %% 4. Relationships
    %% Organized flow: Customer -> System -> Dependencies
    Rel(customer, dashboard_api, "Views Dashboard", "HTTPS/JSON")
    Rel(dashboard_api, redis, "Reads cached data", "TCP")
    Rel(dashboard_api, mainframe, "Syncs data nightly", "SOAP")

    %% Optional: Update Layout to spread things out if needed
    %% UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

3. The “Out of Scope” (The Shield) #

This is the most valuable section for the Engineering Manager. List explicitly what this system will NOT do.

• “We will NOT support multi-currency accounts in this MVP.”
• “We will NOT migrate the historical data from 2019.”
• Why: This prevents “Scope Creep” halfway through the sprint.

4. The Decision Log (Trade-offs) #

Don’t just say “We chose PostgreSQL.” Say Why and What we rejected. This is often called an ADR (Architecture Decision Record).

5. Data Flow (The “Happy Path”) #

Do not write paragraphs. Use a sequence diagram. “User clicks button -> API receives request -> Service A checks Cache -> Service B updates DB.” Engineers build mental models from flows, not prose.

The “Living Document” Fallacy #

People say, “Keep the SDD living!” Real Logic: You won’t. Once code is written, the code is the truth. The SDD will rot.

The Fix: Treat the SDD as a “Design-Time” artifact. Once the project is live, do not try to keep the SDD updated with every bug fix. Instead, update the README.md in the repo. The SDD records the intent and the decisions at the start. The Code records the reality at the end.

Conclusion #

Respect your reader’s time.

• Use bullet points.
• Use diagrams.
• Be honest about risks (“This part of the design is shaky”).
• If you can’t explain the logic in 3 pages, you haven’t simplified the architecture enough.