Architecture Oral History Minimalist Techniques for Describing - - PDF document

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

• f 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

• f 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 mkeeling@neverletdown.net http://neverletdown.net

54