Slide 1
Slide 1 text
“WE’RE AGILE, WE DON’T
DO DOCUMENTATION”
@birgitta410
B i r g i t t a B ö c k e l e r
Slide 2
Slide 2 text
No content
Slide 3
Slide 3 text
“Documenting Software Architectures – Views and Beyond”
2nd edition, 2011; Clements, Bachmann, Bass, Garlan, Ivers, Little, Merson, Nord, Stafford
Slide 4
Slide 4 text
No content
Slide 5
Slide 5 text
No content
Slide 6
Slide 6 text
No content
Slide 7
Slide 7 text
No content
Slide 8
Slide 8 text
No content
Slide 9
Slide 9 text
No content
Slide 10
Slide 10 text
DESCRIBING SOFTWARE
Slide 11
Slide 11 text
No content
Slide 12
Slide 12 text
WHERE ARE YOU?
1:1 UML
diagrams
No
documentation
at all
“Self-
documenting
code”
Tests are
readable
specification
Slide 13
Slide 13 text
PURPOSE of
documentation?
Slide 14
Slide 14 text
For the sake
of a PROCESS.
Slide 15
Slide 15 text
PURPOSE of
documentation?
Slide 16
Slide 16 text
Create a
COMMON
UNDERSTANDING.
1
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
The wall of
COMMON
UNDERSTANDING.
Containers &
Tech Stack
Environments
Components …
…
…
Up for grabs!
Slide 19
Slide 19 text
Surface and
understand
COMPLEXITY.
2
Slide 20
Slide 20 text
… …
…
Data schema
migrations
Synching
behavior
…
Design of
storage module
Slide 21
Slide 21 text
INFO GRAPHICS.
Slide 22
Slide 22 text
“WIDGET” KITS.
Slide 23
Slide 23 text
Create EMPATHY.
3
Slide 24
Slide 24 text
Empathy between
TECH DECISION
MAKERS and
developers.
Slide 25
Slide 25 text
“Working on software
without guidance, without documentation,
is anxiety-producing”
https://medium.com/@duretti/no-flex-zone-empathy-driven-development-aebf4d8cf7cf
Empathy with
EACH OTHER.
Slide 26
Slide 26 text
Empathy between
PRODUCT PEOPLE and
developers.
Slide 27
Slide 27 text
Empathy with OTHER
TECHNOLOGISTS.
Slide 28
Slide 28 text
Help our
FUTURE SELVES
make informed
DECISIONS.
4
Slide 29
Slide 29 text
Architecture
DECISION records.
http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
“Without understanding the rationale (…),
only two choices:
1. Blindly accept the decision.
2. Blindly change it.”
Slide 30
Slide 30 text
LIGHTWEIGHT
architecture
DECISION records.
https://github.com/npryce/adr-tools
Slide 31
Slide 31 text
Describe the
PROBLEM, not just
the SOLUTION.
Slide 32
Slide 32 text
CREATIVE
problem
SOLVING.
5
Slide 33
Slide 33 text
No content
Slide 34
Slide 34 text
No content
Slide 35
Slide 35 text
No content
Slide 36
Slide 36 text
No content
Slide 37
Slide 37 text
But how do we
keep it
UP TO DATE?!
Slide 38
Slide 38 text
@kaeff
Slide 39
Slide 39 text
As LITTLE as possible.
Make it VISIBLE.
Include in RITUALS.
Create OWNERSHIP through
COLLABORATION.
Slide 40
Slide 40 text
Help our FUTURE SELVES
make informed DECISIONS.
Surface and understand
COMPLEXITY.
Create
COMMON UNDERSTANDING.
CREATIVE problem SOLVING.
Create EMPATHY.
Slide 41
Slide 41 text
<> Code
THE
TRUTH
HOW-TOs
HISTORY
MAPS
CREATIVE
THINKING
Slide 42
Slide 42 text
“Individuals and interactions”
“Business people and developers
work together daily”
“Face to face communication”
“Attention to
technical excellence and
good design”
“Simplicity”
Slide 43
Slide 43 text
@birgitta410