Making complex product decisions understandable
Context
Platforma is used by scientists to explore and visualize complex biological data.
The feature became a shared dependency for multiple visualization workflows, making consistency and implementation accuracy increasingly important.
The Data Mapping experience evolved into a sophisticated system involving:
- metadata grouping
- recommendation logic
- visualization constraints
- contextual guidance
- interaction patterns
As the feature grew, communicating design decisions became as important as designing the feature itself.
Without clear documentation, implementation details, UX rationale, and system behavior could easily become inconsistent across teams.
Challenge
Create documentation that allows designers and engineers to understand both user-facing behavior and the underlying system decisions.
The documentation needed to:
- communicate UX decisions clearly
- explain recommendation logic
- support developer implementation
- remain useful as the system evolves
- serve as a reference for future workflows
Documentation principles
Document decisions, not screens
Rather than describing individual interface states, the documentation focuses on the underlying design decisions.
Each section follows a consistent structure:
- Problem
- What changed
- Why this improves UX
This makes the reasoning behind the solution easy to understand and revisit.

Separate user value from implementation logic
The documentation distinguishes between:
- user-facing benefits
- implementation logic and system behavior
This separation allows stakeholders to understand the design intent while giving developers enough context to implement the solution correctly.

Explain complex behavior through progressive disclosure
Instead of introducing all concepts at once, the documentation breaks interactions into small, understandable parts.
The documentation introduces concepts incrementally, moving from simple interface improvements to advanced interaction and recommendation logic.
Each concept is introduced independently before showing how it contributes to the overall experience.

Turn feature decisions into platform knowledge
The documentation captures reusable interaction patterns rather than feature-specific solutions. This allows future workflows to adopt proven approaches instead of reinventing behavior for each new application.

Why it mattered
- Used as a shared reference by Design and Engineering teams.
- Used as implementation reference.
- Captured UX rationale alongside specifications.
- Established documentation patterns for future workflows.
My role
- Designed the Data Mapping experience, including information architecture, interaction patterns, and recommendation workflows.
- Defined a documentation framework that captures UX rationale, interaction behavior, and system logic separately.
- Created reusable documentation patterns for communicating complex product decisions across teams.
- Partnered with engineering to ensure design intent remained understandable throughout implementation.
Outcome
The project transformed feature documentation from a one-time specification into reusable product knowledge. The resulting framework helps teams understand not only what the interface does, but why it behaves that way, making future workflows easier to design, implement, and evolve.