#nfjs #notes

PresentationsAndArchitecture.md

#Documenting Software Architecture Neal Ford

The presentation started out talking about architecture but ended up primarily discussing presentation patterns and styles. Not a bad talk but not what I was expecting or hoping for.

Weighing Architecture

How do you balance architecture and working software.

Agile Architecture

Who uses UML? A couple of people raised their hands half heartedly.

Fowler's "UML Distilled" ignores most of UML so it is the best book.

Diagramming Techniques

• Titles - keep them short and meaningful
• Arrows - use unidirectional arrows (double headed almost always a bad idea, ambiguous)
• Layout - sticky notes and index cards, if it took you days to make the diagram you won't change it
• Colors - add an extra dimension
• Shapes - don't expect people know what a shape means, be consistent

4+1 view model

C4

Simon Brown created it based on 4+1

1. Context - who and what interacts with the system
2. Container - deployable pieces
3. Components - these are all the things in the system that do actual work
4. Class - lowest level design things

Structerizer creates diagrams from a DSL. https://github.com/structurizr/java

Probably more structure than it is worth.

Representational consistency

Don't change scale or abstraction within a diagram.

Diagrams as archeological evidence

Architecture needs to be kept up to date. Current and archeology.

'Current' are things being kept up to date. 'Archeology' are things you no longer keep up to date.

Architecture Decision Records

We keep a collection of records of 'Architectural Significance' so we can look up why architectural decisions were made.

A small file kept in with your source code.

/doc/arch/adr-NNN.md

mxd/architecture/archive/ mxd/architecture/archive/

• Title a descriptive title
• Context forces as play
• Decision: what decision was made
• Status: proposed, accepted, superceeded

https://github.com/npryce/adr-tools

Neal emphasized AsciiDoctor tool.

Passive Voice

You make the object of the action the subject.

"Why did the chicken cross the road" --passive--> "Why was the road crossed by the chicken" --> "Why was the road crossed."

Passive voice makes it easy to hide information which may be picked up on if you are hiding it or not.

Passive Voice Myths

• Any use of 'to be' - using 'is' instead

When to use it

When you ARE trying to hide something.

• "Mistakes were made" when you want to avoid blame

Revise the stuff that you write.

When you are an architect you need to realize you have to communicate with people who are not developers.

Technical Writing

• simple, declarative sentances
• draft & rewrite
• spell, grammar check
• use a trusted first reader

Document or Slide Deck?

When I present slides I control when you see it. Documents allow the reader to see it.

Ford's book "Presentation Patterns"

Presentations

Avoid:

• hard transitions
• too much text
• don't use auto-resizing
• "Bullet Riddled Corpse"

Infodeck versus Presentation

An infodeck is used for passing around by email for communication.

Presentation is used to control exposition rate.

A slideument is you are trying to use a duel purpose document.

Speaker notes can be used for details.

Presentation Patterns

Have a a narrative arch

1. introduction
2. exposition
3. climax
4. resolution

A pattern

1. problem
2. solution
3. problem
4. solution
5. exposition
6. problem
7. solution
8. exposition
9. ...
10. overall summary

Avoid >3 points in presentation

People lose track after 3 or so.

Avoid trying to tackle multiple audiences

"Expansion Joists"

Implicit Expansion Joists - practice skipping slides gracefully

Explicit Expansion Joists

Animations

Adds another dimension to your presentation

Magic Move in Keynote

Transparency Shift

Backtracking to emphasize continuity

Cave Painting - Prezi - a slide layout with a huge canvas

• you can use magic move in keynote

Cookie Cutter

Charred Trail fades out the previous points