4/11/2012 1 Creating an Architecture Oral History Michael Keeling Vivísimo @michaelkeeling Minimalist Techniques for Describing Systems 2 Software Architecture Descriptions have some major drawbacks. Documentation is Important…
4/11/2012
1
Creating an
Architecture Oral History
Michael Keeling
Vivísimo
@michaelkeeling
Minimalist Techniques for Describing Systems
2
Software Architecture Descriptions have some major drawbacks.
Documentation is Important…
4/11/2012
2
3
4
Software Architecture Description
SAD
4/11/2012
3
SAD without Purpose?
5
NO!
6
Architecture Documentation is an investment.
4/11/2012
4
7
8
Architecture Documentation
Loans
Lean? Agile?
4/11/2012
5
9
How much? When?
What do I get?
Your Documentation Loan
10
What you document and how you document it should change as the
project evolves.
Documenting Software Architecture
4/11/2012
6
11
Architecture Oral History
12
EARLY IN THE SOFTWARE LIFECYCLE
4/11/2012
7
13
“The easiest time to document the software architecture is at the end of the project… All the hard decisions have already been made!”
– Me, just now
14
Variability in Estimation of Project Scope
Time 0.25x
4x
Steven McConnell, “Software Estimation: Demystifying the Black Art” Anthony Lattanze, “Architecting Software Systems: A Practitioner's guide”
“Period of Uncertainty”
Software Shipped
4/11/2012
8
15
Architecture Description Document
Architecture Written in Stone…
16
4/11/2012
9
17
18
4/11/2012
10
19
20
Visibility Changeability
Understandability
Promoted in Ideal Representations
4/11/2012
11
21
Talk is cheap.
(That’s why it’s so useful!)
22
MIDWAY IN THE SOFTWARE LIFECYCLE
4/11/2012
12
23
“What did we decide last week about this part of the system?”
– My team, a week after our amazing whiteboard discussion
24
Variability in Estimation of Project Scope
Time 0.25x
4x
Steven McConnell, “Software Estimation: Demystifying the Black Art” Anthony Lattanze, “Architecting Software Systems: A Practitioner's guide”
“Period of Uncertainty”
“Period of Certainty”
4/11/2012
13
25
Shift from exploration to construction.
Cusp of Uncertainty/Certainty
26
The Period of Optimistic Certainty
4/11/2012
14
27
Visibility Changeability
Understandability
Promoted in Ideal Representations
Guide-ability
28
System Metaphor Architecture Haiku
Two Example Techniques
4/11/2012
15
29
System Metaphor (Refreshed)
Michael Keeling, “Making Metaphors that Matter,” Agile2011 Experience Report Michael Keeling, “Guidelines for the System Metaphor” http://neverletdown.net/2011/08/guidelines-for-the-system-metaphor/
30
4/11/2012
16
A Good Metaphor…
1. Represents a single view.
2. Deals with only one type of structure.
3. Gives clear guidance concerning design decisions.
4. Sheds light on system properties.
5. Draws on shared experience.
31
Corollary: Even a good metaphor still requires explanation.
4/11/2012
17
UI Business Layer
Services Layer
Server Layer
Utility Layer
34
4/11/2012
18
“Noodles”
Layer
Web Client Overview (Static Perspective) “Bento Box”
Layer A B A is allowed to use elements in B
Legend
Service Layer
Server Layer
Utility
Layer X
Vocabulary Representation Reference Point
Information Payload + System Metaphor
36
4/11/2012
19
37
Architecture Haiku
George Fairbanks, “Architecture Haiku,” http://rhinoresearch.com/content/speaking-boulder-java-user-group-7-sept-2010-architecture-haiku
Architecture Haiku includes
• Solution description
• Summary of architectural drivers
• Quality attribute priorities
• Design rationale and trade-offs
• Architectural styles/patterns used
• Diagrams
38
All on a single page!
4/11/2012
20
A Recent Haiku at Vivísimo…
39
Vivísimo’s Architecture Haiku Rules
• One page in Visio
• No font smaller than 10pt
• Should follow basic template
• Diagrams optional
– Velocity Patterns Catalog
• Assume a requirements document exists
– Customer communication, planning
40
4/11/2012
21
Haiku + System Metaphor…
41
Architecture Styles/Patterns 3-tier (data, crawl, query) Source-Selector – promotes reliability Double Redundancy – promotes availability Virtual Documents – all data crawled Document Enqueue – for website data Collection Farm – promotes crawl-ability Geolocation Lookup – promotes maintainability/modifiability
Architecture Styles/Patterns 3-tier (data, crawl, query) Source-Selector – promotes reliability Double Redundancy – promotes availability Virtual Documents – all data crawled Document Enqueue – for website data Collection Farm – promotes crawl-ability Geolocation Lookup – promotes maintainability/modifiability
42
LATE IN THE SOFTWARE LIFECYCLE
4/11/2012
22
43
“The easiest time to document the software architecture is at the end of the project… All the hard decisions have already been made!”
– Me, about 11 minutes ago
44
Shift from Creating to Releasing and Maintaining.
Change Becomes Expensive
4/11/2012
23
45
Most Knowledge Least Rework
Time to Move on
Now is the Time to Document
46
Architecture oral history collapses without a team to
keep the culture alive.
4/11/2012
24
47
CREATING AN ARCHITECTURE ORAL
HISTORY
48
Architecture oral history requires that the team is both willing and able to retell the stories and keep
the oral history alive.
Core Assumption
4/11/2012
25
Essential Knowledge
• Basics of architectural drivers
• Simple quality attribute scenarios
• Static, dynamic, physical structures
• Basics of architectural styles/patterns
• Identify (and evaluate) trade-offs
49
50
Size of Project Size of Team
Collocated vs. Distributed Team Experience
Mileage May Vary - Adjust Accordingly
4/11/2012
26
Evolution is not Simple…
51 51
Knowledge
Time
Elements or Subsystems
To Review…
52
Variability in Estimation of Project Scope
Time 0.25x
4x
Stay Light! Codify Decisions as Oral History
Delay Formality!
4/11/2012
27
We’re Already Doing This…
53
Discussing Whiteboarding
Sketching Talking in Metaphors
Thank you!
Michael Keeling
@michaelkeeling
http://neverletdown.net 54