Architecture Decisions: Documentation Governance

OVERVIEW

SAP LeanIX helps enterprise architects map and govern complex IT landscapes. But there was no native way to capture why decisions were made. Teams kept Architecture Decision Records in Confluence, SharePoint, and spreadsheets, completely disconnected from the architecture they were documenting.

GOAL

Bring Architecture Decision Records natively into LeanIX, giving enterprise architects a structured, flexible way to document, govern, and link decisions directly to their technology landscape.

YEAR

2025

ROLE

Design Owner
UX Strategy

SKILLS

0→1 Product Design
UX Research
UI & UX Design

THE CHALLENGE

LeanIX showed architects what existed in their landscape. It had no way to capture why.

Architecture Decision Records are a mature, opinionated practice with real conventions, established workflows, and deeply held opinions. Designing for this domain required immersion, not assumption. I joined with no existing designs, no design precedent in the product, and a set of layered constraints to navigate simultaneously.

THE IMPACT

From zero to platform-wide adoption in the months following GA.

The feature launched to General Availability in Q1 2025, following an Early Adopter Program with 23 enterprise customers including SAP SE, Deutsche Bahn, Mercedes-Benz, DHL, PwC, Nestlé, ALDI Süd, and MediaMarktSaturn.

The Amplitude data captures what happened after:

Signal

What the data shows

Enterprise customers at GA

1,300+

Unique users (Collaboration Tab)

Reached ~23,378 unique users within months of GA

Engagement growth

2–3× across 4 releases

Weekly retention

~70%

Role distribution

Adoption spread across Admins, Members, Viewers, and Architects — not concentrated in power users

Post-GA roadmap

5 follow-on Architecture Decisions features released in Q2 2025.


5 follow-on features shipping in Q2 2025 — including Fact Sheet backlinking, diagram previews, and options comparison — signal sustained organizational investment in the feature's foundation.

The Problem

Architects knew their landscape. They had no way to explain it.

ADRs are a mature practice. Every organization had their own format, tooling, and conventions. None of it connected to LeanIX.

Key gaps:

  • Decisions scattered across Confluence, SharePoint, improvised Fact Sheet workarounds

  • No link between a decision and the architecture it affected

  • Governance was happening entirely outside the platform built to enable it

Research and Insights

A specialized domain, no playbook, and a tight timeline.

Architecture Decision Records are a mature, opinionated practice. Enterprise architects have strong conventions around them and no patience for tools that ignore those conventions.

I immersed myself in the domain fast: reviewing existing session recordings, conducting desk research, and embedding directly into customer discovery to observe real workflows and ask behavioral follow-ups.

What the research revealed:

  • Overlapping structure: common sections appeared across every customer's ADR regardless of company or tooling

  • Diverging content: what went inside those sections varied significantly by organization

  • No universal format: but common building blocks could serve everyone

This gap between structure and content became the design principle that drove every decision that followed.

Snippet of synthesis showing overlapping vs divergent ADR elements across customers

Solution:
Step 1

Answer the structural question before designing anything.

Should Architecture Decisions live in LeanIX's meta model as a new Fact Sheet type?

No one had a clear answer. I assessed the risk: touching the meta model meant cascading dependencies, increased cost, and potential disruption to existing customer data at scale — disproportionate to what the feature needed to do.

Decision: Build Architecture Decisions as a document artifact linked to Fact Sheets — not as one.

Design decisions:

  • Used LeanIX's existing "Documents" concept as the structural foundation

  • Preserved full value: contextual linking, structured content, searchability

  • Contained scope and dependencies — keeping GA on track

  • Required cross-functional alignment with PM and EM before any UI work began

Visualization of Decisions as Document vs Fact sheet + connection hierarchy

Solution:
Step 2

Structured flexibility and the thinking behind it.

The research revealed a real tension: half of customers needed strict templates, the other half would reject anything rigid. The answer wasn't a compromise. It was a more precise reading of the problem.

Structure mattered at the section level. Content varied at the field level. Prescribing both would break the feature for too many users.

Core design decision: a modular component system.



Design decisions:

  • Rich-text as the primary component: a mental model users already have, zero learning curve.

  • Handles content diversity without custom solutions for every case

  • Additional components such as date pickers, user fields, status, references. All freely stackable.

  • Users compose what their process requires; the system doesn't impose one (but it does offer a best-practice template for those that need one.)

Every user gets the same building blocks. How they assemble them is up to them.

This shipped at GA and remains the core of the templates feature today.

Solution:
Step 3

Connect decisions to the architecture they affect without disrupting what already exists.

Linking Architecture Decisions to Fact Sheets was the feature's core value. But Fact Sheets were simultaneously undergoing a major layout redesign making this a coordination problem as much as a design one.

Design decisions:

  • Coordinated directly with the Fact Sheet lead designer to avoid conflicts mid-redesign

  • Kept integration footprint minimal: maximum value, minimum disruption

  • Back-linking from Fact Sheets → Decisions scoped as follow-on, shipped Q2 2025

Limitations

Shipping right mattered more than shipping everything.

The push was to build broadly and move fast. I advocated for a tighter MVP. In enterprise governance, a poorly considered feature creates trust debt that's hard to recover from.

Components designed but sequenced post-GA i.e. options comparison, diagram previews, both shipped in Q2 2025, validating the call.

Two practices that kept the team moving:

  • Co-design rituals with engineering: constraints surfaced early, no late-breaking blockers

  • Design system championship: contributed LeanIX-specific patterns during the SAP Horizon migration, and led a navigational patterns workshop that shaped how users access the Documents module across the platform

Future opportunities

The feature has data. The next step is making it intelligent.

  • Decision surfacing: suggest relevant past decisions when drafting a new one

  • Pattern recognition: surface recurring themes across the organization's landscape

  • Governance health: flag decisions overdue for review

The infrastructure exists. The opportunity is designing institutional memory with a point of view.

Smooth Scroll
This will hide itself!

Architecture Decisions: Documentation Governance

OVERVIEW

SAP LeanIX helps enterprise architects map and govern complex IT landscapes. But there was no native way to capture why decisions were made. Teams kept Architecture Decision Records in Confluence, SharePoint, and spreadsheets, completely disconnected from the architecture they were documenting.

GOAL

Bring Architecture Decision Records natively into LeanIX, giving enterprise architects a structured, flexible way to document, govern, and link decisions directly to their technology landscape.

YEAR

2025

ROLE

Design Owner
UX Strategy

SKILLS

0→1 Product Design
UX Research
UI & UX Design

THE CHALLENGE

LeanIX showed architects what existed in their landscape. It had no way to capture why.

Architecture Decision Records are a mature, opinionated practice with real conventions, established workflows, and deeply held opinions. Designing for this domain required immersion, not assumption. I joined with no existing designs, no design precedent in the product, and a set of layered constraints to navigate simultaneously.

THE IMPACT

From zero to platform-wide adoption in the months following GA.

The feature launched to General Availability in Q1 2025, following an Early Adopter Program with 23 enterprise customers including SAP SE, Deutsche Bahn, Mercedes-Benz, DHL, PwC, Nestlé, ALDI Süd, and MediaMarktSaturn.

The Amplitude data captures what happened after:

Signal

What the data shows

Enterprise customers at GA

1,300+

Unique users (Collaboration Tab)

Reached ~23,378 unique users within months of GA

Engagement growth

2–3× across 4 releases

Weekly retention

~70%

Role distribution

Adoption spread across Admins, Members, Viewers, and Architects — not concentrated in power users

Post-GA roadmap

5 follow-on Architecture Decisions features released in Q2 2025.


5 follow-on features shipping in Q2 2025 — including Fact Sheet backlinking, diagram previews, and options comparison — signal sustained organizational investment in the feature's foundation.

The Problem

Architects knew their landscape. They had no way to explain it.

ADRs are a mature practice. Every organization had their own format, tooling, and conventions. None of it connected to LeanIX.

Key gaps:

  • Decisions scattered across Confluence, SharePoint, improvised Fact Sheet workarounds

  • No link between a decision and the architecture it affected

  • Governance was happening entirely outside the platform built to enable it

Research and Insights

A specialized domain, no playbook, and a tight timeline.

Architecture Decision Records are a mature, opinionated practice. Enterprise architects have strong conventions around them and no patience for tools that ignore those conventions.

I immersed myself in the domain fast: reviewing existing session recordings, conducting desk research, and embedding directly into customer discovery to observe real workflows and ask behavioral follow-ups.

What the research revealed:

  • Overlapping structure: common sections appeared across every customer's ADR regardless of company or tooling

  • Diverging content: what went inside those sections varied significantly by organization

  • No universal format: but common building blocks could serve everyone

This gap between structure and content became the design principle that drove every decision that followed.

Snippet of synthesis showing overlapping vs divergent ADR elements across customers

Solution:
Step 1

Answer the structural question before designing anything.

Should Architecture Decisions live in LeanIX's meta model as a new Fact Sheet type?

No one had a clear answer. I assessed the risk: touching the meta model meant cascading dependencies, increased cost, and potential disruption to existing customer data at scale — disproportionate to what the feature needed to do.

Decision: Build Architecture Decisions as a document artifact linked to Fact Sheets — not as one.

Design decisions:

  • Used LeanIX's existing "Documents" concept as the structural foundation

  • Preserved full value: contextual linking, structured content, searchability

  • Contained scope and dependencies — keeping GA on track

  • Required cross-functional alignment with PM and EM before any UI work began

Visualization of Decisions as Document vs Fact sheet + connection hierarchy

Solution:
Step 2

Structured flexibility and the thinking behind it.

The research revealed a real tension: half of customers needed strict templates, the other half would reject anything rigid. The answer wasn't a compromise. It was a more precise reading of the problem.

Structure mattered at the section level. Content varied at the field level. Prescribing both would break the feature for too many users.

Core design decision: a modular component system.



Design decisions:

  • Rich-text as the primary component: a mental model users already have, zero learning curve.

  • Handles content diversity without custom solutions for every case

  • Additional components such as date pickers, user fields, status, references. All freely stackable.

  • Users compose what their process requires; the system doesn't impose one (but it does offer a best-practice template for those that need one.)

Every user gets the same building blocks. How they assemble them is up to them.

This shipped at GA and remains the core of the templates feature today.

Solution:
Step 3

Connect decisions to the architecture they affect without disrupting what already exists.

Linking Architecture Decisions to Fact Sheets was the feature's core value. But Fact Sheets were simultaneously undergoing a major layout redesign making this a coordination problem as much as a design one.

Design decisions:

  • Coordinated directly with the Fact Sheet lead designer to avoid conflicts mid-redesign

  • Kept integration footprint minimal: maximum value, minimum disruption

  • Back-linking from Fact Sheets → Decisions scoped as follow-on, shipped Q2 2025

Limitations

Shipping right mattered more than shipping everything.

The push was to build broadly and move fast. I advocated for a tighter MVP. In enterprise governance, a poorly considered feature creates trust debt that's hard to recover from.

Components designed but sequenced post-GA i.e. options comparison, diagram previews, both shipped in Q2 2025, validating the call.

Two practices that kept the team moving:

  • Co-design rituals with engineering: constraints surfaced early, no late-breaking blockers

  • Design system championship: contributed LeanIX-specific patterns during the SAP Horizon migration, and led a navigational patterns workshop that shaped how users access the Documents module across the platform

Future opportunities

The feature has data. The next step is making it intelligent.

  • Decision surfacing: suggest relevant past decisions when drafting a new one

  • Pattern recognition: surface recurring themes across the organization's landscape

  • Governance health: flag decisions overdue for review

The infrastructure exists. The opportunity is designing institutional memory with a point of view.

Smooth Scroll
This will hide itself!

Architecture Decisions: Documentation Governance

OVERVIEW

SAP LeanIX helps enterprise architects map and govern complex IT landscapes. But there was no native way to capture why decisions were made. Teams kept Architecture Decision Records in Confluence, SharePoint, and spreadsheets, completely disconnected from the architecture they were documenting.

GOAL

Bring Architecture Decision Records natively into LeanIX, giving enterprise architects a structured, flexible way to document, govern, and link decisions directly to their technology landscape.

YEAR

2025

ROLE

Design Owner
UX Strategy

SKILLS

0→1 Product Design
UX Research
UI & UX Design

THE CHALLENGE

LeanIX showed architects what existed in their landscape. It had no way to capture why.

Architecture Decision Records are a mature, opinionated practice with real conventions, established workflows, and deeply held opinions. Designing for this domain required immersion, not assumption. I joined with no existing designs, no design precedent in the product, and a set of layered constraints to navigate simultaneously.

THE IMPACT

From zero to platform-wide adoption in the months following GA.

The feature launched to General Availability in Q1 2025, following an Early Adopter Program with 23 enterprise customers including SAP SE, Deutsche Bahn, Mercedes-Benz, DHL, PwC, Nestlé, ALDI Süd, and MediaMarktSaturn.

The Amplitude data captures what happened after:

Signal

What the data shows

Enterprise customers at GA

1,300+

Unique users (Collaboration Tab)

Reached ~23,378 unique users within months of GA

Engagement growth

2–3× across 4 releases

Weekly retention

~70%

Role distribution

Adoption spread across Admins, Members, Viewers, and Architects — not concentrated in power users

Post-GA roadmap

5 follow-on Architecture Decisions features released in Q2 2025.


5 follow-on features shipping in Q2 2025 — including Fact Sheet backlinking, diagram previews, and options comparison — signal sustained organizational investment in the feature's foundation.

The Problem

Architects knew their landscape. They had no way to explain it.

ADRs are a mature practice. Every organization had their own format, tooling, and conventions. None of it connected to LeanIX.

Key gaps:

  • Decisions scattered across Confluence, SharePoint, improvised Fact Sheet workarounds

  • No link between a decision and the architecture it affected

  • Governance was happening entirely outside the platform built to enable it

Research and Insights

A specialized domain, no playbook, and a tight timeline.

Architecture Decision Records are a mature, opinionated practice. Enterprise architects have strong conventions around them and no patience for tools that ignore those conventions.

I immersed myself in the domain fast: reviewing existing session recordings, conducting desk research, and embedding directly into customer discovery to observe real workflows and ask behavioral follow-ups.

What the research revealed:

  • Overlapping structure: common sections appeared across every customer's ADR regardless of company or tooling

  • Diverging content: what went inside those sections varied significantly by organization

  • No universal format: but common building blocks could serve everyone

This gap between structure and content became the design principle that drove every decision that followed.

Snippet of synthesis showing overlapping vs divergent ADR elements across customers

Solution:
Step 1

Answer the structural question before designing anything.

Should Architecture Decisions live in LeanIX's meta model as a new Fact Sheet type?

No one had a clear answer. I assessed the risk: touching the meta model meant cascading dependencies, increased cost, and potential disruption to existing customer data at scale — disproportionate to what the feature needed to do.

Decision: Build Architecture Decisions as a document artifact linked to Fact Sheets — not as one.

Design decisions:

  • Used LeanIX's existing "Documents" concept as the structural foundation

  • Preserved full value: contextual linking, structured content, searchability

  • Contained scope and dependencies — keeping GA on track

  • Required cross-functional alignment with PM and EM before any UI work began

Visualization of Decisions as Document vs Fact sheet + connection hierarchy

Solution:
Step 2

Structured flexibility and the thinking behind it.

The research revealed a real tension: half of customers needed strict templates, the other half would reject anything rigid. The answer wasn't a compromise. It was a more precise reading of the problem.

Structure mattered at the section level. Content varied at the field level. Prescribing both would break the feature for too many users.

Core design decision: a modular component system.



Design decisions:

  • Rich-text as the primary component: a mental model users already have, zero learning curve.

  • Handles content diversity without custom solutions for every case

  • Additional components such as date pickers, user fields, status, references. All freely stackable.

  • Users compose what their process requires; the system doesn't impose one (but it does offer a best-practice template for those that need one.)

Every user gets the same building blocks. How they assemble them is up to them.

This shipped at GA and remains the core of the templates feature today.

Solution:
Step 3

Connect decisions to the architecture they affect without disrupting what already exists.

Linking Architecture Decisions to Fact Sheets was the feature's core value. But Fact Sheets were simultaneously undergoing a major layout redesign making this a coordination problem as much as a design one.

Design decisions:

  • Coordinated directly with the Fact Sheet lead designer to avoid conflicts mid-redesign

  • Kept integration footprint minimal: maximum value, minimum disruption

  • Back-linking from Fact Sheets → Decisions scoped as follow-on, shipped Q2 2025

Limitations

Shipping right mattered more than shipping everything.

The push was to build broadly and move fast. I advocated for a tighter MVP. In enterprise governance, a poorly considered feature creates trust debt that's hard to recover from.

Components designed but sequenced post-GA i.e. options comparison, diagram previews, both shipped in Q2 2025, validating the call.

Two practices that kept the team moving:

  • Co-design rituals with engineering: constraints surfaced early, no late-breaking blockers

  • Design system championship: contributed LeanIX-specific patterns during the SAP Horizon migration, and led a navigational patterns workshop that shaped how users access the Documents module across the platform

Future opportunities

The feature has data. The next step is making it intelligent.

  • Decision surfacing: suggest relevant past decisions when drafting a new one

  • Pattern recognition: surface recurring themes across the organization's landscape

  • Governance health: flag decisions overdue for review

The infrastructure exists. The opportunity is designing institutional memory with a point of view.

Smooth Scroll
This will hide itself!

Create a free website with Framer, the website builder loved by startups, designers and agencies.