Visual Design and Architecture
Ruth Malan

Code is Design
#OReillySACon

Code as Design
1992
“software [..] design is the source
code listings”
“programming is about designing
software”
– Jack Reeves
https://www.developerdotstar.com/

Code as Design
https://www.developerdotstar.com/
2005
"In software engineering, we desperately need
good design at all levels. [..]
Designers should use anything that helps.”

Code as Design
https://www.developerdotstar.com/
2005

@RuthMalan
#OReillySACon
“Our highest priority is to
satisfy the customer through
early and continuous delivery
of valuable software.”
Agile Principles
#OReillySACon
Source: https://agilemanifesto.org/principles.html

@RuthMalan
#OReillySACon
Faces of design:
• Design of working software:
What the system is
(requirements: capabilities and
properties)
• Design of code: How it is built
and how it works (architecture
and design: structure and
dynamics)
Design
#OReillySACon
developer facinguser facing
operations facing

Agile Design
• users respond to working software with
needs/ideas; (co-)evolve to better design
• TDD (Test Driven Development/Design) and
refactor to better code design
Iterative and incremental
• get frequent feedback
• respond and adapt
Agile Design
developer facinguser facing
codesoftware

the Code is the Design
#OReillySACon

@RuthMalan
#OReillySACon
“The best architectures,
requirements, and designs
emerge from self-organizing
teams.”
Agile Principles
#OReillySACon
Source: https://agilemanifesto.org/principles.html

“Good design doesn’t ‘emerge’
like a welcome ray of sunshine
on a cloudy day.
—Erik Dietrich
Erik Dietrich, Designs Don’t Emerge
http://www.daedtech.com/designs-dont-emerge/
Good Design

“It comes coughing, sputtering,
screaming and grunting from
the mud, like a drowning man
being pulled from quicksand,
and the effort of dragging it
laboriously out leaves you
exhausted.”
—Erik Dietrich
http://www.daedtech.com/designs-dont-emerge/
Art by Amanda Muledy (@EEKitsabug)
Good Design

Code is Design
#OReillySACon

@RuthMalan
#OReillySACon
All good. Question is, can we do better? If so, how?
What is missing if all we have is code (with tests, obviously)?
Or what is code less good at, in terms of helping us do, or
express, design?
As we do design, can we give ourselves more of a cognitive
assist and collective intelligence boost?
Agile Design
#OReillySACon

@RuthMalan
#OReillySACon
Alternately put, the code is sufficient design expression for a
compiler to build it, but is it sufficient for humans to design
and evolve complex systems?
We have a lot of “undocumented” code which is abundant
existence proof of something; but can we do better?
Agile Design
#OReillySACon

“The engineer, and more
generally the designer, is
concerned with how things
ought to be - how they ought to
be in order to attain goals, and
to function.”
— Herbert Simon
What is Design?
What are we talking about,
when we talk about design?

“Architecture represents the
significant design decisions that
shape a system”
— Grady Booch
What is Architecture?

“Some decisions are consequential
and irreversible or nearly
irreversible [..] these decisions
must be made methodically,
carefully, slowly, with great
deliberation and consultation”
— Jeff Bezos, letter to shareholders, 2015
Irreversible Decisions
Image source: wikipedia

“If you walk through and don’t like
what you see on the other side,
you can’t get back to where you
were before.”
— Jeff Bezos, letter to shareholders, 2015
Irreversible Decisions

“But most decisions aren’t like that –
they are changeable, reversible – they’re
two-way doors. If you’ve made a
suboptimal [reversible] decision, you
don’t have to live with the consequences
for that long. You can reopen the door
and go back through.”
— Jeff Bezos, letter to shareholders, 2015
Reversible Decisions

Architecture Decisions
“Architecture represents the
significant design decisions that
shape a system, where
significant is measured by cost
of change.”
— Grady Booch

Architecture Decisions
• Significant is measured by
cost of change
• Decisions to reduce cost of change (make reversible)
• Decisions that have high cost of change (irreversible)

Architecture Decisions
“Software architecture is the
set of design decisions
which, if made incorrectly,
may cause your project to
be cancelled.”
– Eoin Woods

Architecturally significant?
• Cost of change
• Strategic
• Address challenges
• create systems with desired
capabilities and properties
• under forces and constraints
• that are demanding, push
the limits, require design
attention
Architecture Decisions
make or break
}
“deliberate
deliberately”
— Dawn Ahukanna

Questions about whether design is
necessary or affordable are quite
beside the point: design is
inevitable.
The alternative to good design is
bad design, not no design at all.
— Douglas Martin
The No Decision Decision

Decisions Constrain
“Constraints alter the probability
distribution of the available
alternatives. They make a system
diverge from chance, randomness, or
equiprobability”
‘Limiting or closing off alternatives is
the most common understanding of
the term “constraint.”’
— Alicia Juarrero
Photo by Will Evans, LeanUX 2015

Constraints Enable
But if all constraints restricted a
thing's degrees of freedom in this
way, organisms (whether
phylogenetically or
developmentally) would
progressively do less and less.’
— Alicia Juarrero

Constraints Enable
“constraints not only reduce the
alternatives — they also create
alternatives. Constraints, that is,
can also create properties which a
component exhibits in virtue of its
embeddedness in a system,
properties it would otherwise not
have.”
— Alicia Juarrero
“Causality as Contraint”

“We put ground under our
feet, by deciding”
Architecture Decisions
— Dana Bredemeyer
Probe and test design ideas as
quickly and cheaply as we can
(while still reversible)

@RuthMalan
#OReillySACon
All good. Question is, can we do better? If so, how?
What is missing if all we have is code (with tests, obviously)?
Or what is code less good at, in terms of helping us do, or
express, design?
As we do design, can we give ourselves more of a cognitive
and collective intelligence boost?
Just Enough Architecture
#OReillySACon

@RuthMalan
#OReillySACon
Title: short noun phrase
Context: desired outcomes and the forces
at play (probably in tension)
Decision: describes our response to these
forces
Status: proposed, accepted, deprecated or
superseded
Consequences: describes the resulting
context, after applying the decision — Michael Nygard, Documenting
Architecture Decisions, Nov 2011
Architecture Decisions
#OReillySACon
@mtnygard

@RuthMalan
#OReillySACon
Title: short noun phrase
Context: desired outcomes and the forces
at play (probably in tension)
Decision: statement of the decision
Status: proposed, accepted, deprecated or
superseded
Consequences: describes the resulting
context, after applying the decision
— Michael Nygard, Documenting
Architecture Decisions, Nov 2011
Architecture Decisions
#OReillySACon
@mtnygard

@RuthMalan
#OReillySACon
Microservices: Tradeoffs
#OReillySACon
“Microservices: gain scalability and fault
tolerance at the price of additional
complexity in managing a distributed
system”
This! This right here! This is architectural thinking. Perceiving
where there are tradeoffs. It takes experience, but also a
system perspective. Noticing that what happens in one
place, can have non-local or differently timed consequences
and implications.

Mattias Petter Johansson, Quora

Mattias Petter Johansson, Quora

@RuthMalan
#OReillySACon
"The value of every decision we make
depends on the context in which we
make it. In The Lord of the Rings,
Frodo’s journey to destroy the ring is
meaningful inside the context of Middle
Earth. Otherwise, he’s a short, hairy guy
with apocalyptic hallucinations."
– Diana Montalion
Decisions in Context
#OReillySACon

Context: Factors
Image source: Sarah Mei on Twitter
“Design quality is not a
property of the code. It's
a joint property of the
code and the context in
which it exists.”
– Sarah Mei

@RuthMalan
#OReillySACon
For me, “engineer” means knowing that
all decisions are tradeoffs. It means
considering both upsides & downsides
of each technical choice, and doing so
with explicit consideration of the larger
system context.
– Sarah Mei
Decisions: Tradeoffs
#OReillySACon
@sarahmei

When things get heated, spot the differences in (perceived)
context and the tradeoffs being weighed (or ignored)!
Decisions: Tradeoffs
Image by Dave Grey in “Liminal thinking The pyramid of belief”

@RuthMalan
#OReillySACon
Title: short noun phrase
Context: desired outcomes and the forces
at play (probably in tension)
Decision: describes our response to these
forces
Status: proposed, accepted, deprecated or
superseded
Consequences: describes the resulting
context, after applying the decision — Michael Nygard, Documenting
Architecture Decisions, Nov 2011
Architecture Decisions
#OReillySACon
@mtnygard

Architecture Decisions
Making Decisions Conveying Decisions
How to do this better

@RuthMalan
#OReillySACon
How Do We Start?
• To make a decision, we need to have a
(good enough) conception of
– Desired outcome(s)
– Forces and constraints
– Consequences and side-effects

@RuthMalan
#OReillySACon
How Do We Start?
To make a decision, we need to have a (good enough)
conception of
• Desired outcome(s)
• Forces and constraints
Arising in context of
• development
• operations
• use
• value network
[as relevant]

@RuthMalan
#OReillySACon
Title: short noun phrase
Context: desired outcomes and the forces
at play (probably in tension)
Decision: describes our response to these
forces
Status: proposed, accepted, deprecated or
superseded
Consequences: describes the resulting
context, after applying the decision
Architecture Decisions
“formulating the problem is
the problem”
– Horst Rittel
#OReillySACon

As Theory Building

@RuthMalan
#OReillySACon
Design in Context
#OReillySACon
“Always design a thing by
considering it in its next
larger context.”
— Eliel Saarinen

in its next larger context
Context System-in-Context
(use, dev, ops)
System
(Ecosystem)
Strategy
Ecosystem
interventions
Requirements
Design of system
capabilities
Architecture
Structure and
mechanisms

Ask
• [not just] What do users need?
• [but also] What do developers and testing need?
• [and] What does operations need?
• [and] What do others in the value network need?
To Develop Theory of “the Problem”

Context: the Landscape
Context Map, David Sibbet, Visual Meetings

Context: the Landscape

Context: the Landscape

Context: the Landscape

Context: the Landscape

Context: the Landscape
CaringCircles Competitive Landscape

Context: Systems of Systems
“sketchprototype” with Rich Pictures
Show
• structure
• value flows and transformations
• concerns
CaringCircles
Rich Picture

Who’s Impacted? Empathy
Imaginative entry
into the
experience of:
• Users of
various kinds
• Developers
and testers
• Operations
• Senior
management
• Support/call
center
• Value chain
partners

Who’s Impacted? Goals
Stakeholder Profile
• Stakeholder
• Responsibilities
• Business/Personal
Goals
• System Goals
• Value Proposition
Stakeholder: Business Owner
Responsibilities:
• Funding model
• Securing user data
• Hiring good talent

Other Ecosystem Views
Business Model Canvas
By Alexander Osterwalder
and Yves Pigneur
Wardley Maps
By Simon Wardley

System in Context
Customer Journey Maps
Event Storming
Alberto Brandolini

Exploring System Design
Maps, maps and more maps
• Impact maps: goal, who can impact
goal (+/-) and how can they
obstruct/help, what can we deliver to
support impact/goal
• Assumptions maps: desirable: do they
want this; feasible: can we do this;
viable: should we do this
• User story maps
impactmapping.org
David Bland
agilebuddha.com

What’s Going on Here??
Product Owners and User Experience
Designers, step aside — Ruth’s bringing in
the architects!
Not that!
Partner well (but just enough), to bring
technology capabilities to design table,
and to build up “theory of the problem” to
inform design choices/decisions

System on a Page
Also! Designing the
System:
• Significant system
capabilities
CaringCircles Use Case Diagram
Use cases
Facilitate caring circle
• Enroll members
• Inform members
Characterize requests
View and adopt requests
Make offers

System in Context
Manage tribe
membership
Manage user
profile
View
content
Assemble
content
Techtribes Use Case Diagram (UML)
Techtribes Context Diagram (Simon Brown’s C4)

Architectural design is system design. System
design is contextual design — it is inherently about
boundaries (what’s in, what’s out,
what spans, what moves between).
It reshapes what is outside, just as it shapes
what is inside.
Contextual Design

System Design
“The defining properties
of any system, are
properties of the whole,
which none of the parts
have. If you take the
system apart, it loses its
essential properties”
— Russell Ackoff

Context: Properties
“Quality doesn't happen by magic.”
– Rebecca Wirfs-Brock

Context: Properties
Quality Attributes Kiviat: Michael Keeling

Context: Properties
Landing Zones: Rebecca Wirfs-Brock

System Design: Forces
Source: Grady Booch

Just Enough Just in Time
“I always say to myself,
what is the most
important thing we can
think about at this
extraordinary moment.”
– Bucky Fuller

Iterative Design
Let go of the need to
be “done”
Test, iterate and
refactor applies to
models too
Source: wikipedia.org/wiki/OODA_loop
OODA is a loop!

@RuthMalan
#OReillySACon
Recall our question: Can we do better than our already good
Agile practices with their focus on code (TDD, refactoring,
frequent feedback, …)? If so, how?
What is missing from code, or what is code less good at, in
terms of design?
• Big picture
• Structures and relationships; Interactions
• Assumptions
• Alternatives
Agile Design
#OReillySACon

@RuthMalan
#OReillySACon
Visual: Drawing on the Walls
• Chauvet Cave
• film "Cave of Forgotten Dreams"
– 30,000–33,000 years ago
• Chauvet Cave Art
– only guess at their purpose, meaning
– did serve to record
Image: wikimedia commons

@RuthMalan
#OReillySACon
Visual: Drawing on the Walls
Image: from film “Hidden Figures”
Source: http://daily.gatech.edu
• Engineering
• the film “Hidden Figures”
• Drawing on the walls
– To think (together)
– To illustrate,
communicate

Visual: Drawing in notebooks
Leonardo Da Vinci’s
notebooks:
used sketches to
• observe (more attentively)
• study, think, reason,
to puzzle things out
• understand

Visual Notebooks
Sketching
• To record
– to think longer, harder
– to show, to teach
• To invent, to design, to
combine, to make (new)
connections
• To test ideas
– thought experiments
Leonardo Da Vinci Notebooks

Constitution of the United
States: the architecture of
US government
Architecture Document

Federalist papers
• Arguments describing and
motivating mechanisms of
government architecture
Federalist Papers, No. 51
addresses
• checks and balances
• separation of powers
White Paper

Technical Memo
1995

Visual: Annotated Sketches

@RuthMalan
#OReillySACon
Visual
“The primary use for diagrams
and documentation is
communication and learning”
— Simon Brown
@simonbrown

@RuthMalan
#OReillySACon
Visual Design
The primary use for diagrams in design is
better design
• the act: doing design
• the outcome: expressing design

@RuthMalan
#OReillySACon
Visual
Image: theatlantic.com
“Does a Spider Use Its Web Like You Use Your Smartphone?”
• Cognition
– extended into the
world
• Spider webs
– we use the world
to think

@RuthMalan
#OReillySACon
Source: Rudolf Arnheim
• Consider the following problem
– One morning, exactly at 8 A.M., a monk began to climb a tall mountain.
The narrow path, no more than a foot or two wide, spiraled around the
mountain to a glittering temple at the summit. The monk ascended the
path at varying rates of speed, stopping many times along the way to
rest and to eat the dried fruit he carried with him. He reached the
temple precisely at 8 P.M.
The next day, he began his journey back along the same path, starting at
8A.M. and again walking at varying speeds with many pauses along the
way. He reached the bottom at precisely 8 P.M.
– I assert that there is at least one spot along the path the monk occupied
at precisely the same time of day on both trips.
– Is my assertion true? How do you decide?

Visual Thinking
Source: Rudolf Arnheim, Visual Thinking, 1969

Visual
• To abstract
• To reason
• To show
• To test
• To document
• To transform
To address wicked problems:
To deal with complexity
- buffer overflow!
To work together/collaborate
- shared thought-space
To communicate
- explain, defend, preserve

We value “people and interactions” – collaboration
We value convening collaboration, convening the
creation of more shared mental models, more shared
context and system understanding.
Conveying is important – too. We convene to convey.
And convey to convene. Visual design is a crucible for
conversation.
Visual: to Convene and Convey

System Design
“A system is an
interconnected set of
elements that is
coherently organized in a
way that achieves
something”
-- Donella Meadows

Software architecture refers to the high level
structures of a software system [..] Each
structure comprises software elements,
relations among them, and properties of both
elements and relations.
— wikipedia/Clements et al

@RuthMalan
#OReillySACon
Not Agile?
#OReillySACon
• Rigid: not able to be changed or adapted
• entangled
• Inertia: the resistance of the object to any change in its
motion, including a change in direction

Good: Architecture 💔
“You reach for the
banana, and get the
entire gorilla”
– Michael Stahl
Not

“we have to keep it crisp,
disentangled, and simple if we
refuse to be crushed by the
complexities of our own
making...”
— Dijkstra
Good: Crisp, disentangled

Decoupled modular structure
Good: Reversible
• Isolate impact of change
• Isolate arenas of uncertainty and experiment
• Increase replaceability
• Increase responsiveness/adaptability
• Manage complexity
• separate concerns, reveal intent: increase
comprehensibility

The architect’s SCARS:
• Separation of Concerns
• crisp and resilient
Abstractions
• balanced distribution of
Responsibilities
• strive to Simplify — Grady Booch
Good: Architecture

“I go along with the natural
makeup”…
“when I come to the tricky parts,
I slow down”
— Chuang Tzu:
“The Dexterous Butcher”
SCARS: Separation of Concerns

As programmers we deal
with abstractions all the
time and we have to invent
them in order to solve our
problems
— Michael Feathers
SCARS: Abstractions
@mfeathers

SCARS: crisp Abstractions
"To find the right abstraction, guess. If it exhibits the
right properties, stop. "— Jessica Kerr
@jessitron

Recall: Capabilities
CaringCircles Use Case Diagram
Use cases
Facilitate caring circle
• Enroll members
• Inform members
Characterize requests
View and adopt requests
Make offers
View and claim offers
Fulfill requests

Components: Guess

Components: Guess
Requestor
Service
CaringCircle
Service
Requests
Service
Offers
Service
Matching
Service
• Setup requestor
account
• Inform and
update requestor
• Setup caring circle
• Enroll members
• Inform members
• Enter offers
• Update offers
• View offers
• Claim offers
• View offers status
• Enter requests
• Update requests
• View requests
• Claim requests
• View requests
status
• Match requests
and offers

Recall: Capabilities
CaringCircles Use Case Diagram
Use cases
Facilitate caring circle
• Enroll members
• Inform members
Characterize requests
View and adopt requests
Make offers
View and claim offers
Fulfil requests

SCARS: crisp Abstractions
“Things that are cohesive, [..] naturally stick to
each other because they are of like kind, or
because they fit so well together.[..] the
pieces all seem to be related, they seem to
belong together, and it would feel somewhat
unnatural (it would result in tight coupling!) to
pull them apart”
— Glenn Vanderburg

Components: Guess
Requestor
Service
CaringCircle
Service
Requests
Service
Offers
Service
Matching
Service
• Setup requestor
account
• Inform and
update requestor
• Setup caring circle
• Enroll members
• Inform members
• Entry offers
• Update offers
• View offers
• Claim offers
• View offers status
• Enter requests
• Update requests
• View requests
• Claim requests
• View requests
status
• Match requests
and offers

Components: Next Guess
Requestor
Service
CaringCircle
Service
Requests
Service
Offers
Service
Matching
Service
• Setup requestor
account
• Inform and
update requestor
• Setup caring circle
• Enroll members
• Inform members
• Enter offers
• Update offers
• View offers
status
• Enter requests
• Update requests
• View requests
status
• Match requests
and offers
o Manual match
o Automated
match
Fulfilment
Service

Factor and Refactor
SCARS: crisp Abstractions
“The responsibility of architecture
is the architecture of responsibility.”
— Jan van Til/Tom Graves
Does this component have a
cohesive identity or purpose — a
single responsibility at the level of
abstraction of the abstraction?

“We propose instead that one
begins with a list of difficult
design decisions or design
decisions which are likely to
change. Each module is then
designed to hide such a
decision from the others.”
— David Parnas
SCARS: crisp and resilient Abstractions
1972

Recall: System Capabilities
Manage tribe
membership
Manage user
profile
View
content
Assemble
content
Techtribes Use Case Diagram (UML)
Techtribes Context Diagram by Simon Brown (in C4)

Techtribes Component Diagram
by Simon Brown [in C4]
SCARS: Abstractions

SCARS: Separation of Concerns
Hexagonal Architecture
Alistair Cockburn
Ports and adapters

Design across
“Design is not just what it
looks like and feels like.
Design is how it works.”
— Steve Jobs

Posit structure Explore behavior
Revise structure
Explore — with sketches
Structure and Behavior

What
ARCHITECTURE
STRUCTURE
interfaces
elements and
relationships
How
BEHAVIOR
Logical
Conceptual

Structure and Behavior

Structure and Behavior
:CustomerMgr :HotelMgr
:ReservationSystem
1 makeAReservation
1.1 getCustomer 1.2 makeReservation
1.3 notifyCustomer

Exploring Behavior
source: VisualParadigm

Systems: Deployment Diagram

“Don’t partition by slicing through regions where
high rates of information exchange are required” –
Eb Rechtin
Systems: Interfaces
Image source: Martin Fowler’s bliki

Iterative: Messy, Backtrack

119
System Design Intention
(what should be)
System Design Reflection
(what is)

“at least they’re looking at it”
• sketch prototype
• try alternatives on
the cheap
• “mob modeling”
• “test drive”
Visual models

“Architects must have
self-repairing egos”
— Dana Bredemeyer

Expose your mental models to the open air.
Remember, always, that everything you know,
and everything everyone knows, is only a
model.
Get your model out there where it can be shot
at.
Invite others to challenge your assumptions and
add their own.
Instead of becoming a champion for one
possible explanation or hypothesis or model,
collect as many as possible.
— Donella Meadows
Image source: Donella Meadows Institute
Change Your Point of View

Change Your Point of View
“A change of
perspective is worth
80 IQ points”
— Alan Kay

“You don't understand
something until you
understand it more
than one way”
— Marvin Minsky
Image:
wikipedia.org/wiki/Marvin_Minsky#/media/File:Marvin_Minsky_at_OLPCb.jpg
Change Your Point of View

“If you haven’t thought of
three possibilities, you
haven’t thought enough.”
— Jerry Weinberg
Rule of Three
Change Your Point of View

Agile Design
• in models and code
• visual design is also a way to test and refactor to
improve
Iterative and incremental
• get frequent feedback
• respond and adapt
Agile Design: Now with Pictures
developer facinguser facing
codesoftware

@RuthMalan
#OReillySACon
Making It Visual
Ruth Malan
Web: bredemeyer.com
also: ruthmalan.com
Twitter: @ruthmalan