- This is a short tour of visualizing, documenting,

and exploring software architecture.

And we're gonna start here.

Sorry, imagine we've invented teleporters

and I teleport you here, where are you?

France?

Close, but not quite.

So yeah, it says La Rue de something.

This is what happens when we drop new joiners

into a code base.

We kind of drop them straight into the middle of it

and they're a bit lost.

How do we solve this problem?

How do we figure out where we are?

We zoom out, we use technology, we open up

the maps on our phone and start zooming out.

Any better?

Not zoomed out enough.

Well, you can now see the name of the road,

but we're not quite sure still where we are.

We zoom out one more time.

Yeah, there we go.

So that shows you that's where I live.

There's a lot of cluttering on this map, isn't there?

It's not very, very clear to see what's going on.

So with things like Google Maps, we can reduce

the amount of information.

Like that.

Gets a bit clearer, now we can start to see

some of the place names and where some

of the bits and pieces are.

If you've never heard of Jersey before,

this is still kind of useless so you have

to pinch to zoom out one more time.

And again.

And again.

So now there you go, there's Jersey.

It's a small island just off the coast of France.

Now, if you come and visit Jersey, which you should

because it's lovely, when you come through the airport

you'll get a map.

And this is a traditional Visitor Map thing

and it shows you information like this.

The map's broken up into four quarters

and it kind of tells you enough information to get around.

It tells you enough information to go and find

the major sites and that sort of thing.

It doesn't tell you everything though.

It's not listing every street, it's not listing

every building on every street either.

There's a zoomed in part for town, the main city,

and we've got a little bit more detail on it,

but it's a representations, it's not quite accurate.

So this thing here, this blue bit,

the tide actually goes out there.

So if you pull into Jersey and you boat and you park there,

you will find it dry at some point.

And also, this bathing pool here.

It looks like it never gets refreshed with water,

but it does, which is useful because I'm sure

kids pee in it in the summer. (audience laughs)

The thing these maps have in common

is that they show points of interest.

So what do I really want to go and see when I visit Jersey?

Contrast this with like an ordnance survey map.

This is a very, very detailed representation of Jersey.

We've got contours and different types of land

and all sorts of things going on here.

And you need a bit of intelligence and some help

to get started interpreting this thing.

Both maps are showing selected highlights as well.

And that's a really interesting thing here,

selected highlights.

So when you come to Jersey next year on your summer holiday,

you'll probably drive past this big castle.

It's called Elizabeth Castle, it's on

the south coast from the sea.

And it's a 16th century castle,

some beautiful granite blockwork,

and it was basically built to stop

the French and English taking Jersey over.

And when you walk around this castle,

you kind of get to the top in the middle

and things start to change.

And you've got this beautiful granite stone thing

with this weird concrete thing stuck on top for some reason.

And you're like, "That looks really weird.

"What's all that about?"

And history's important here, so when you're walking

around the castle, it tells you that

in World War Two when the Germans occupied Jersey,

they refortified some of the existing fortifications.

So that's what that big concrete thing is on the top

and those sorts of gun replacements

and so on and so forth.

Of course, all of this stuff is described in guide books

and there are lots of them out there

and of course, if you want to be a bit hipster,

you can use the website.

We have the Internet now.

So that's my quick introduction and sales pitch

for Jersey, I guess.

I'm gonna come back to the same thing.

Right, so visualization.

One of the things I do with software teams

around the world is I run a visualization workshop

and we give some people some requirements.

So we say, "Right, you have 90 minutes in groups

"to go draw some pictures."

And these are the types of pictures people actually draw.

I promise I have not made any of these up.

I'm not sure I could make these things up.

Do these look like diagrams you see on your whiteboards?

Yes.

(audience laughs)

I have another 15 gigabytes I could show you,

but I won't.

Sometimes when I'm running this workshop,

I actually hear people say this.

Right, so they're drawing a box or a shape and they say,

"This doesn't make sense, but we'll explain it later

"when we do our presentation or something."

And that's fine, but we don't always present

our diagrams, do we?

Now, if we're drawing a picture out of our system,

we don't always stand there and present it.

And a nasty trick I like to do is I like

to have two teams swap diagrams.

And guess what happens?

Because they weren't part of that conversation

creating those diagrams, they have no idea

what's going on and they're at this

kind of Wat moment. (audience laughs)

And they're mad about the color coding

and the shapes and the lines and basically

none of the notations on it makes any sense whatsoever.

When you ask people, "Was this an easy exercise?",

they say, "Well, actually yeah it was."

And then you say, "Well, why are your diagrams such a mess?"

and they go "Oh yeah, good point."

We don't really know what to draw, we're not sure

what sort of diagrams we should draw,

the levels of details, shapes, notations,

should we use UML?

Who here uses UML?

That's a really small number, like four or five people.

So what's everybody else doing?

Something else. (laughs)

I've asked this question around the world

and UML is massively falling out of fashion.

I have no evidence to back any of this up,

this is all completely anecdotal, but I'm seeing

more and more teams who have no UML skills

in the teams anymore.

I do use UML, but I use is sparingly

for small parts for a software system.

What I want to show are very small parts

of say, a class hierarchy or something.

Google doesn't help.

If you go to Google and ask it what it thinks

a software architecture diagram looks like, you get this.

Page after page after page of essentially

pretty-colored block pictures,

the sorts of things you can do in a Visio or PowerPoint.

And we laugh at these things, but these are exactly

the types of diagrams I see when I go

and visit organizations.

You open up their conference pages or whatever,

bang, you get this sort of stuff.

And half the pictures just don't make any sense at all.

This is hard.

I think I've run this workshop for about 10,000 people now,

all around the world, and nobody does it

sufficiently well the first time around, believe it or not.

And the irony here is Agile.

So one of the great things Agile has done

is it's made us more visual.

Whenever I go and visit Agile organizations,

you've got their camera boards and the storywalls

and the information dashboards.

So we've gotten awesome at visualizing,

essentially processing the way we work.

We've totally forgotten how to draw pictures

of the things we're building.

And this is just about good communication.

If you want to move fast as a team,

if you want business agility,

then you need to communicate well, that's it.

So there's some really simple tips here

around notation that I could give you.

And just stuff like put titles and pictures,

make sure your arrows are annotated,

make sure your arrows point one way,

and so on and so forth.

And the notation around drawing architecture diagrams

is really, really easy to fix.

One of my key points is this one here, responsibilities.

We often joke that naming is hard in software,

so it doesn't make sense that most

of our architecture diagrams are essentially

just a collection of named boxes

because the diagrams contain a huge amount of ambiguity.

So my simple tip is add more text to your diagrams.

And here's a really simple example.

This is the same diagram, the version

on the right has more text.

And that additional text allows us to see things

like the responsibilities of those building blocks.

There's a lot more information there.

In terms of content, when we're drawing

architecture diagrams you can't show everything

on a single picture.

And this is why people do talk about things

like views and viewpoints and perspectives.

And there are lots and lots of different ways to do this.

I would mention Philippe Kruchten's 4 + 1 model

as a book that details a whole bunch of ways to do this

and there are more.

The thing is all of those view catalogs

have this logical view of a system

separate to the development view of the system.

So the logical view is often either

the functional, logical, conceptual building blocks

and then there's something else that refers to

how we're building these things.

Why?

Why do we do this?

I don't get it.

Because whenever I go to organizations

and I see their nice, fluffy logical architecture diagrams,

they never match the code.

And that's kind of the point here.

If I'm drawing architecture diagrams,

I need them to match the code.

Otherwise, they're just lying to me.

George Fairbanks is sitting in the back.

He calls this the model-code gap in his awesome book.

When we're having architecture discussion,

we're using abstract concepts

like modules and components and services,

but we don't have those same things

in our programming languages.

Quick show of hands, who's a Java developer here?

Right, so in Java is there a layer keyword?

No.

In Java is there a component keyword?

No, but we create components and layers

by assembling classes and interfaces and packages

and things together.

So what I'm trying to get to is a set of diagrams