apidays LIVE Australia 2021 - Accelerating Digital
September 15 & 16, 2021
Re-thinking Software Architecture Documentation
Graham Lea, Co-Founder at Archium
4. 500,000 BC
Speech & Language
Broke the constraint of:
Limited expression
Tim Evanson
5. New York
JULY
Australia
SEPTEMBER
Singapore
APRIL
Helsinki & North
MARCH
Paris
DECEMBER
London
OCTOBER
Jakarta
FEBRUARY
Hong Kong
AUGUST
JUNE
India
MAY
Check out our API Conferences here
50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees,
300k+ online community
Want to talk at one of our conferences?
Apply to speak here
25. The Documentation Stereotype
Architect in corner office writing specs?
Software architecture documentation:
knowledge-sharing, unconstrained by time,
location, and departmental partitions
39. Architecture Knowledge Flow
The creation of
architecture
knowledge is
decentralised
Contributing to
knowledge flow has
to become part of
everybody’s role
40. Architecture Knowledge Flow
DevOps & Microservices
decouple teams’ delivery
But teams are still
depending on the work
on others at runtime,
and have others
depending on them
Service
Service Service
Service
Service
Service
41. Architecture Knowledge Flow
Service
Service Service
Service
Service
Service
Team Team
Team
Team Team Team
DevOps & Microservices
decouple teams’ delivery
But teams are still
depending on the work
on others at runtime,
and have others
depending on them
42. Architecture Knowledge Flow
Teams need inbound
knowledge flow to give
them confidence that
they’re integrating
correctly
Service
Service Service
Service
Service
Service
Team Team
Team
Team Team Team
43. Architecture Knowledge Flow
Teams should provide
outbound knowledge flow
to to their dependents to
minimise confusion,
failures, and expensive
coordination
Service
Service Service
Service
Service
Service
Team Team
Team
Team Team Team
44. Architecture Knowledge Flow
P.S. Good knowledge
flow almost always
goes both ways
Service
Service Service
Service
Service
Service
Team Team
Team
Team Team Team
45. Architecture Knowledge Flow
Agile means there’s
far fewer big plans.
Each team is building
their own plan as
they go, and maybe
updating it daily.
46. Architecture Knowledge Flow
Agile means there’s
far fewer big plans.
Each team is building
their own plan as
they go, and maybe
updating it daily.
47. Architecture Knowledge Flow
These changes create
new knowledge that
needs to flow to people
whose upcoming
decisions and work
might depend on them
48. Architecture Knowledge Flow
These changes create
new knowledge that
needs to flow to people
whose upcoming
decisions and work
might depend on them
50. Architecture Knowledge Flow
Teams need access to
knowledge about the
high-level design and
behaviour of the system
to understand what it
does and how they can
improve it
Twitter
51. Architecture Knowledge Flow
The complexity means a
single big picture is
probably useless
This “big picture”
knowledge needs to be
filterable, linked, and
explorable Twitter
66. Changes to systems have become
frequent, iterative, and automated
Knowledge flow needs to follow suit:
frequent, iterative, and automated
Increasing Knowledge Flow
67. Here’s the approaches agile
orgs are using to increase
architecture knowledge flow
Increasing Knowledge Flow
77. Architecture Decision Records
New team members can learn
why things are the way they are
With rationale recorded, we can see when the
decision is no longer relevant
79. Service Catalogues
Describe every service,
in brief, in one place
List the most important
info people need
Link to other sources
with more detail
State Library of NSW
80. Service Catalogues
Not as technical as design docs
Ideal overview for new starters, testers,
Ops, management, Product
92. Draw manually
e.g. draw.io, Gliffy, whiteboard
Big Advantage:
Full control over appearance
Disadvantages:
Time-consuming
Quickly obsolete
Architecture Diagrams
93. Create a model manually
e.g. Archi, MagicDraw
Big Advantage:
Generate multiple views
Disadvantages:
Still time-consuming
Quickly obsolete
Architecture Diagrams
94. Generate from text DSL
e.g. Mermaid JS, PlantUML
Big Advantages:
Faster
Focus on information
Disadvantage:
Still gets obsolete
Architecture Diagrams
95. Generate a model from code
e.g. Structurizr
Big Advantage:
As up to date as annotations
Disadvantage:
Internal architecture
Architecture Diagrams
96. Generate model from telemetry
e.g. Archium
Advantages:
Represents reality of prod
Examine many views
Filter, explore
Disadvantage:
Needs broad telemetry
Architecture Diagrams
97. How do people discover diagrams?
Architecture Diagrams
98. How do people discover diagrams?
Think about creating a diagram catalogue
Or link from a service catalogue
Architecture Diagrams
101. Living Documentation
Set of practices for
automating the creation
and maintenance of
documentation so that it
changes at the same pace
as the system
114. Knowledge Flow: Wrap-Up
Software Engineering has changed
We’re optimising for rapid change &
decentralised, autonomous design
Knowledge flow is more important than ever
116. Knowledge Flow: Wrap-Up
Big Design Up Front
Architect
Finalised specs
Stale documents
No Design Up Front
No one
No documentation
Ad hoc oral history
117. Knowledge Flow: Wrap-Up
Big Design Up Front
Architect
Finalised specs
Stale documents
No Design Up Front
No one
No docs
Ad hoc oral history
Just Enough Design Up Front
Teams
Living Documentation
Continuous Knowledge Flow
119. New York
JULY
Australia
SEPTEMBER
Singapore
APRIL
Helsinki & North
MARCH
Paris
DECEMBER
London
OCTOBER
Jakarta
FEBRUARY
Hong Kong
AUGUST
JUNE
India
MAY
Check out our API Conferences here
50+ events since 2012, 14 countries, 2,000+ speakers, 50,000+ attendees,
300k+ online community
Want to talk at one of our conferences?
Apply to speak here