If Your SDR Had Feelings, It’d Be Disappointed in You
Written by Tara Patoile, Adobe data & insights practitioner
The Bite-Sized Breakdown
If your Solution Design Reference (SDR) could talk, it wouldn’t be furious. It would just sigh.
Why? Because no one’s opened it in months. It knows half the team is guessing how things were built. It knows someone just asked, “Wait… why does this metric work like that?” — and three people gave three different answers.
An SDR isn’t supposed to be some ceremonial spreadsheet you build once and never touch again. It’s the running record of how your analytics actually works. The decisions. The logic. The weird edge cases that made it into production at 11:47 p.m. on a Thursday.
This post isn’t glorifying the documentation as much as it’s about making it less mysterious, and way less painful. In environments like Adobe Customer Journey Analytics… complexity sneaks up fast. When no one remembers how the system works, things get confusing AND expensive.
Let’s fix that.
So, What the Heck Is a Solution Design Reference (SDR)?
If you’ve ever been on a team where someone says: “Wait… how did we build this?” and everyone just stares into the void… congratulations, you’ve lived in SDR purgatory.
An SDR document is basically the source of truth for your solution’s design. It explains:
what the system is doing,
how it does it,
and why it’s doing it that way.
It’s supposed to be both the blueprint and the memory bank for how your implementation actually works. This isn’t a product roadmap — it’s the record of big decisions, tiny decisions, and all the weird edge cases that made it into production.
Fun fact: Adobe calls this exact thing a Solution Design Reference (SDR) and recommends you think of it as the glue between your business requirements and your implementation. (Creating and Maintaining an SDR)
Why SDRs Matter…Even If You’d Rather Eat Keyboard Dust
Here’s the brutal truth: SDR docs go far beyond a “nice to have.”
Without them, you get:
Total confusion — developers reinventing wheels.
Mystery bugs — because no one knows why something was built they way it was.
Onboarding hell — new team members flail around like they’re in a corn maze without a map.
Think about updating your SDRs like brushing your teeth: you can ignore it once, but eventually things decay and you end up having to pay to resolve it (time is money).
Good documentation helps with softening the blow to every stakeholder. When everyone knows what the solution is, and where decisions live, you avoid unnecessary debates later.
The Hot Mess Without SDRs
You’ve seen this before:
“Can someone tell me why this metric shows weird numbers in prod?”
crickets
“Who added this field? Some intern in 2019?”
even louder crickets
Without a central reference, your system becomes like a haunted house full of undocumented traps. That’s why SDRs are a team lifesaver, not an optional Slack status update.
Automation to the Rescue (Thank You, Brian Au)
Now here’s the part where we give credit where it’s due.
Enter Brian Au’s CJA Auto SDR generator — created by Brian Au, Principal Product Manager for Customer Journey Analytics. This thing takes the pain out of manual SDR creation for Adobe Customer Journey Analytics.
Instead of:
Copying & pasting spreadsheets,
Manually listing every metric,
Desperately Googling what that field actually does,
you automate extraction, formatting, and diffing. It even tracks changes over time and spits out documentation in multiple formats. In other words: It finally treats documentation like code… versioned, testable, and sane.
If SDRs make your vision blurry, tools like this are your contact lenses (or glasses, whatever floats your boat). They prove SDRs don’t have to be boring or manual. In fact, they can be a living artifact that evolves as your solution evolves.
*DISCLAIMER* And to be crystal clear, this is not an Adobe-supported tool. Brian is just awesome and finding ways to leverage AI to help customers/end users of CJA.
SDRs Aren’t Just Pretty PDFs
Documentation is all about compliance and clarity:
What is this field for?
Why did we make it required?
How does it behave in edge cases?
A good SDR answers all that. And when you keep it updated — lo and behold — you stop wasting time answering the same questions in Slack over and over again.
SDRs for the Win
Reading old documentation that’s out of date feels like reading product specifications from the pre-historic era. If an SDR is older than your latest sprint, it’s about as useful as a sundial in a cave.
That’s precisely why you update it. Not later. Not “maybe.” Now. Because future you will curse present you otherwise.
So friends, here are the takeaways:
SDR documents are the on-the-record, factual description of your implementation.
They keep chaos at bay when teams scale.
They save grief when someone inevitably asks “But where did that come from?”
And with automation tools (like Brian Au’s generator), they’re actually attainable, not mythical artifacts.
If you want a team that moves fast without crashing into itself, SDRs are essential.
Reference Links for Light Reading
Brian Au’s CJA Auto SDR Code: https://github.com/brian-a-au/cja_auto_sdr/releases
Brian Au’s Change Log (for the Auto SDR… since this is an evolving tool): https://github.com/brian-a-au/cja_auto_sdr/blob/main/CHANGELOG.md