This document discusses the importance of design in software development. It explores how code represents design decisions, but notes that code alone may not provide all the context needed for complex system design. The document examines how visualizing designs through diagrams, maps, and other means can help teams understand relationships, assumptions, and tradeoffs to make informed architectural decisions. It emphasizes considering systems in their full context, including impacts on users, developers, operations, and other stakeholders. Iterative exploration of designs through visual models supports collaborative thinking and decision-making.
3. Code as Design
1992
“software [..] design is the source
code listings”
“programming is about designing
software”
– Jack Reeves
https://www.developerdotstar.com/
6. @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
7. @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
8. 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
11. “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
12. “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
14. @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
15. @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
16. “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?
18. “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
19. “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
20. “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
22. 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)
24. 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
25. 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
26. 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
27. 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
28. 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”
29. “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)
30. @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
31. @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
32. @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
33. @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.
36. @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
37. 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
38. @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
39. 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”
40. @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
42. @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
43. @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]
44. @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
47. 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
48. 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”
55. Context: Systems of Systems
“sketchprototype” with Rich Pictures
Show
• structure
• value flows and transformations
• concerns
CaringCircles
Rich Picture
56. 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
57. 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
60. 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
61. 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
62. 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
63. 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)
64. 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
65. 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
70. 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
71. 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!
72. @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
73. @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
74. @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
75. Visual: Drawing in notebooks
Leonardo Da Vinci’s
notebooks:
used sketches to
• observe (more attentively)
• study, think, reason,
to puzzle things out
• understand
76. 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
77. Constitution of the United
States: the architecture of
US government
Architecture Document
78. Federalist papers
• Arguments describing and
motivating mechanisms of
government architecture
Federalist Papers, No. 51
addresses
• checks and balances
• separation of powers
White Paper
84. @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?
86. 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
87. 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
88. System Design
“A system is an
interconnected set of
elements that is
coherently organized in a
way that achieves
something”
-- Donella Meadows
89. 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
92. “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
93. 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
94. The architect’s SCARS:
• Separation of Concerns
• crisp and resilient
Abstractions
• balanced distribution of
Responsibilities
• strive to Simplify — Grady Booch
Good: Architecture
95. “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
96. 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
97. SCARS: crisp Abstractions
"To find the right abstraction, guess. If it exhibits the
right properties, stop. "— Jessica Kerr
@jessitron
98. 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
101. 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
102. 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
105. 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?
106. “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
107. 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)
117. “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
122. 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
123. Change Your Point of View
“A change of
perspective is worth
80 IQ points”
— Alan Kay
124. “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
125. “If you haven’t thought of
three possibilities, you
haven’t thought enough.”
— Jerry Weinberg
Rule of Three
Change Your Point of View
126. 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