Making Decisions –
From Software Architecture Theory
to Practice
@PAvgeriou
P.Avgeriou@rug.nl

Software
Archaeology
Users
Management
Study Toolkit
School
Administration Courseware
Authoring
System
Administration Course
management
Searching
Assessment
Courseware
Delivery
Business Object
Management File
Management
Metadata
Management
Content
Packaging
Communication
Management
Web Delivery
TCP/IP
Main
Calendar
Raw Data
Management
RDBMS
DataStore
access
DBClient
FTP SMTP/IMAP
HTTP
Enterprise
Interoperability
Digital
Library
Libraries
or/and APIs

Eureka!
Architecting is about
making decisions!

Paradigm
Shift
2004-05

Decision-centric
architecting
Design
decisions
&
rationale
Models
Languages
Expertise
skills
successes
best practices
Business
environment
technologies
Concerns
requirements
assumptions
risks
Models
Languages

Decision-centric
architecting
Design
decisions
&
rationale
Models
Languages
Expertise
skills
successes
best practices
Business
environment
technologies
market
Concerns
requirements
assumptions
risks
Architecture
Knowledge

From novelty to mainstream
Perry
& Wolf
42010
Design
decisions
&
rationale

Wait, what is the problem?
Knowledge
vaporization

Codification Personalization

Paradigm
Shift
Codification
Tools
2004-05
2005-10

Codification 101
Knowledge Architect plug-ins
A. Jansen, P. Avgeriou and J. van der Ven, Enriching Software Architecture Documentation. JSS 2009

The Knowledge Architect
A. Jansen, P. Avgeriou and J. van der Ven, Enriching Software Architecture Documentation. JSS 2009

5 tools - We got some things right!
› Understanding core AK concepts & types
› Architecting lifecycle coverage
› Reuse support
A. Tang, P. Avgeriou, A. Jansen, R. Capilla, M. Ali Babar, A Comparative Study of Architecture Knowledge Management Tools, JSS 2010

#Fail

#Fail
Feeding the beast

Paradigm
Shift
Codification
Tools
Sharing AK
2004-05
2005-10
2008-12

What if we could share AK?
Core
AK
repo1
AK
repo3
AK
repo2
AK
repo1
AK
repo2
AK
repo3

P. Liang, A. Jansen, P. Avgeriou, A. Tang, L. Xu, Advanced quality prediction model for software architectural knowledge sharing, JSS 2011
Decision
Topic
Concern
Alternative
Decision Specification
originates from
raises
creates
adresses
chooses
Risk
Requirement

2004 2005 2006 2007 2008 2010 2013 2014
RAT
Archium
AREL
PAKME
ADDSS
Eagle
ADkWik
KA
ADDM*
ADDSS 2.1*
SAW*
ADvISE*
Decision
Architect*
1st Generation
2nd Generation
3rd Generation
ADDSS 2.0
SEURAT
RGT*
* alive/used
R. Capilla, A. Jansen, A. Tang, P. Avgeriou, M. Ali Babar, 10 years of Software Architecture Knowledge Management: Practice
and Future, JSS 2016

#Fail – Translating / Core Metamodel
› ISO 42010 compliant but too much variability
› Core metamodel too narrow
• Organization-, Domain-, Project-specific
› Translation expensive & information loss
Whatever works!
R. Capilla, A. Jansen, A. Tang, P. Avgeriou, M. Ali Babar, 10 years of Software Architecture Knowledge Management: Practice
and Future, JSS 2016

Paradigm
Shift
Codification
Tools
Sharing AK
2004-05
2005-10
2008-12
X
Lightweight
tools
2013-16

Back to the drawing board
› Increased awareness of decision documentation, but
• Not part of toolset
• Cost/benefit unfavorable
› Build a lightweight tool with and for the architects
• Connect with process and tooling
• Just in time
C. Manteuffel, D. Tofan, P. Avgeriou, H. Koziolek, T. Goldschmidt, Decision architect – A decision documentation tool for
industry, JSS 2016.

Decision Architect
Decision
Documentation
Framework
U. van Heesch, P. Avgeriou, R. Hilliard, A documentation framework for architecture decisions, JSS 2012

“Basically everything is targeted that is needed for a
decision documentation.”
“I don't have to use another tool for all my decisions but I
can do it directly where I spend most of my design work;
that's a really big effect for me”
“Sometimes it’s enough to look at the relations to
understand the rationale behind a decision.”
“I would just create more documentation because I have
this tool.”
C. Manteuffel, D. Tofan, P. Avgeriou, H. Koziolek, T. Goldschmidt, Decision architect – A decision documentation tool for
industry, JSS 2016.

Tip of the
iceberg?

State of Practice
› Documenting decisions?
• Aware of importance but mostly informal sharing
› Where to find decisions?
• Requirements & functional/logical/UML views
• Word/Powerpoint/Visio/wiki
R. Capilla, A. Jansen, A. Tang, P. Avgeriou, M. Ali Babar, 10 years of Software Architecture Knowledge Management: Practice
and Future, JSS 2016

Paradigm
Shift
Codification
Tools
Sharing AK
Automated
documentation
2004-05
2005-10
2008-12
2017-23
X
Lightweight
tools
2013-16

Automating
AK documentation

AK meets MSR
</>
{…}

AK in
› “So the approach I propose is...to iterate through the key space on a
per-CF basis, compute a hash...” [CASSANDRA-193].
› “The dependencies between them should be enforced to avoid cyclic
dependencies. At present they all have dependencies on each
other” [HADOOP-3750]
› “This improves the code readability and maintainability” [TAJO-
121]
› Keeping things config-file based has two drawbacks:...”
[CASSANDRA-44]
M. Soliman, M. Galster, P. Avgeriou, An Exploratory Study on Architectural Knowledge in Issue Tracking Systems, ECSA 2021

› AK in Issues has issues
• Majority of issues not architectural
• Rarely tagged as architectural
• Very unstructured
› Lend themselves naturally to ML/NLP
M. Soliman, M. Galster, P. Avgeriou, An Exploratory Study on Architectural Knowledge in Issue Tracking Systems, ECSA 2021
AK in

As good as classifying cat pictures!

Breaking Bad
“Don’t look for good things, look for
bad things”
Architectural Decisions
that Incur
Technical debt
| 35
© Sony Pictures Television

› Design decisions incurring technical debt
• Violation of modularity
• Using obsolete technology
• Adopting non-optimal solutions
› Technical Debt in Architecture
• More impactful and higher priority
• “it prevents production”
Y. Li, M. Soliman, P. Avgeriou, L. Somers, Self-Admitted Technical Debt in the Embedded Systems Industry: An Exploratory
Case Study, IEEE TSE 2023.
AK in {…}

Direct and easy to use
Value-adding
Multiple classifiers
Datasets small & few
Expertise in ML
+ -

Datasets
wanted

AK in</>

A way to
1. Show where bad decisions are in the system
2. Make them visible to the rest of the team
3. Determine when a problem is fixed
4. Find out if the problem reappears in the future
D. Sas, P. Avgeriou, and U. Uyumaz. On the evolution and impact of architectural smells—an industrial case study, Empirical Software
Engineering 2022
AK in</>

A way to
1. Show where bad decisions are in the system
2. Make them visible to the rest of the team
3. Determine when a problem is fixed
4. Find out if the problem reappears in the future
“[...] this will be very useful, for example, to any person coming to the team
or a new architect of a team. Graphs like this will then provide years of
experience in one go.”
D. Sas, P. Avgeriou, and U. Uyumaz. ”On the evolution and impact of architectural smells—an industrial case study, Empirical Software
Engineering 2022
≠Knowledge
vaporization
AK in</>

Paradigm
Shift
Codification
Tools
Sharing AK
Automated
documentation
Arch Bots
Next decade
2004-05
2005-10
2008-12
2017-23
X
Lightweight
tools
2013-16

Architecting +
Dev Bots =
Arch Bots?
Architecting +
Dev Bots =
Arch Bots

Arch Bots
› Mundane architecture house-keeping
• Decision documentation and update (on the fly)
• Check Architecture conformance
• Check out-of-date decisions
› Converse for decision support
› Search for decisions & AK
› Suggest alternative solutions
› Suggest refactorings

Beware of bots bearing gifts
› Bot input critically reviewed
• Descriptive, not prescriptive
• Ethics check
› Trust is crucial
• Elicit requirements from architects!

Stay with the problem
Impact practice
“The life of a software architect is
a long (and sometimes painful)
succession of suboptimal decisions
made partly in the dark“
P. Kruchten

Thank you!
Paradigm
Shift
Codification
Tools
Sharing AK
Automated
documentation
Arch Bots
Next decade
@PAvgeriou
P.Avgeriou@rug.nl
2004-05
2005-10
2008-12
2017-23
X
Lightweight
tools
2013-16

Image Credits
› ‘Feeding the Beast’ created with Starry AI
› ‘Automating AK documentation’ created with Dall-E
› ‘AK meets MSR’ icons from icons8.com
› Cat picture from Loukas Avgeriou
› ‘Architecting + Dev Bots = Arch Bots’ from depositphotos.com
› ‘IoT & Block-chain’ created with Dall-E
The rest of the pictures are licensed with Creative Commons without
attribution