Creating an Architecture Oral History...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

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

mkeeling@neverletdown.net

http://neverletdown.net 54