(calm piano music) – 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 that actually reflect the code there. That’s my ultimate goal. Before we can even attempt
to solve this problem, we have a bigger problem. And that is a lack of any sort of consistent standard language. Yeah, even in 2016 we don’t
have a consistent vocabulary to talk about software architecture. We think we do, but I don’t think we do. Quiz time, what’s this? It’s a map of London, right? What’s the blue thing? It’s a river, it’s the River Thames. What is a river? Body of water flowing one
or other direction, perfect. So we know what a river
is and we can go and find other rivers using our knowledge. What’s that? It’s a floor plan for a bathroom. What’s this thing here? That’s a toilet. What is a toilet? Right, you know what a toilet is. And again, we could use our knowledge of what a toilet is to
go and find more toilets. Any electrical people here? Electrical engineers? A couple of ways to refer
to circuit diagrams. You’ve got a funny cartoon pictorial thing or a schematic version. What’s that squiggly
line there at the bottom? It’s a resistor, what’s a resistor? It resists stuff, it
slows currents down, yeah. If I had a box of
electrical components here at the front with capacitors
and switches and resistors, could you come to the front and find me a resistor in that box? Right, so you know how
to identify a resistor and if you know the color
coding, you can work at how strong it is. Right, this quiz is too easy. Let’s ramp up the complexity
on an exponential scale. What’s that? (audience laughs) So we have two UML component diagrams. One is a 1.x version and
one is a 2.x version. Don’t ask me which one’s
which, I’ve forgotten. What are the boxes on these diagrams? They are components, correct. What is a component? I don’t know. It’s a logical, abstract,
functional building block thing. And these components
are all very different, so this one down here is
a stereotyped database and there’s a JDBC interface. So that sounds like a database component. These ones are UIs, or applications. What’s the stuff in the middle? Business components, where do they run? In the database as part of the app? Are they micro services? This diagram is open to lots
and lots of interpretation. Look, more text on diagram. If this diagram had more
text, at least we’d know what these things were. To put this very, very
simply, imagine we’re building a really simple system consisting of a web app and a database. The word component means part of. For some people, the
web app is a component of the entire system. For others, something
like a logging component is a component of the web app. Same word, different
levels of abstraction. It’s the ubiquitous language thing. Now, we’ve been going
on for years about DDD and having this ubiquitous language between us and the business people. We don’t have that ubiquitous
language for ourselves and that’s the problem
that we need to solve here. UML tried to do too much. It was a standard notation
and a standard abstraction and it kind of failed on both counts. And I think for where we are
currently in the industry, we need that standard set of abstractions. I would like to get to something
like electrical engineering in the future so we have a standard set of funny symbols to represent things, but let’s get the language nailed first. And the thing here is that
the language we create need to reflect the
technology that we’re using. So I want to merge the logical
and developmental views back together again and collapse them so we have real terminology
that maps to real technology. Now, I don’t know how we
do this on a global scale, but what we can do within
the boundaries of this room is I can show you how I do this. And for me very simply,
when I’m discussing a software system, that software system is made up of containers. A container is just something
that stores data or runs code. In real terms, it’s a
web app, a mobile app, a standalone app, a Windows service, a database schema, and so on. If you open up the containers, they are made up of components. So I want to use the word
components to mean something running inside a run-time
environment, essentially. It’s a nice cohesive grouping of stuff with a nice, clear
interface and we’re done. And because I mostly
deal with Java and C#, my components are built from classes. That’s it. It’s a really simple
hierarchical tree structure to describe the static
structure of software system. If you’re using JavaScript,
this makes no sense. So maybe it’s modules and objects or modules and functions. Same with functional languages, modules and functions. If you’re using a database technology, maybe it’s components
and stored procedures. So again, you have to take
the same hierarchical approach and map it to the tech that you’re using. And this is really about creating a single, simple static
model of a software system. From the system as a
black box down to the code with a couple of levels in between. So that’s the language defined. Once you define a language, you can draw some diagrams really simply. And this is what I like to
refer to as my C4 model. It’s a context diagram, you
zoom in to see the containers, you zoom in to see the components, and you can go down to
code if you want to, but I don’t normally do this,
especially if I’m trying to describe an existing
code base for example. Really quick example. I created this site called Tech Tribes when I moved back to Jersey and it’s just a simple content aggregated
for the local tech industry. This is a context diagram for Tech Tribes. The thing with the monkey
is the system I built. There are different types of users and different system dependencies. If this was an interactive Google Map, we could select, pinch to zoom in. We see the containers
inside the system boundary. We select a container,
we pinch to zoom in, we show the components inside
it, and so on and so forth. It’s just a really simple
hierarchical diagram that map onto that language. And ultimately we get to the code. And ultimately, ideally
there’s a nice, clean mapping between all of these
layers and this actually does reflect what the code looks like. For me, diagrams are maps. Right, that’s the summary
of all of this stuff. Basically, diagrams are maps and you need different types of maps
depending on how much information you have about the thing
you want to learn about or the audience that you’re speaking to. So business people, non-technical people, a nice high-level view works well. Me as a developer, something low-level. Maybe some operations people,
something in the middle. I don’t want you to take away
any tips around notation. This is the notation that I use just because it’s very simple. And I tend to use things
like color coding and shapes to supplement an existing
diagram that already makes sense. So this is the same diagram. One version has some shapes,
which one do you prefer? Probably the one with the shapes. But fundamentally, there’s
no more information on either diagram, it’s
just an aesthetic thing. I also think it’s worth
just pointing out that there are lots of other things
you might want to consider when you’re describing
your software architecture. And this is where all of
the views and viewpoints and perspectives stuff comes into play and I will point you to
Philippe Kruchten’s work as well and Eoin Woods’s book. This C4 thing is not a design process, it’s just a set of diagrams. And it’s a set of
diagrams that you can use during an up front design
exercise or even retrospectively, so if you have an existing code base with no documentation, this is
a really good starting point. Yes. (laughs) I get this question a lot. What tool do you recommend? Please don’t say Visio again. Because this is just a
set of boxes and lines, any general purpose
diagramming tool will do. Visio, OmniGraffle, Gliffy,
whatever you choose. But come on, this is 2016. There was an interesting plea
for help on Twitter recently. What tools are there for
creating architecture slides? Nobody responded with a modeling tool. It was all general
purpose diagramming tools, which I think is just nuts. And if you look at the building industry, the building industry does not use Visio. The building industry creates
a three dimensional model of that building and they
surface different views from it. The irony again of course
is we build these tools for the building sector. (laughs) And we can’t do this ourselves. So I’m trying to solve
lots of problems here and one of my approaches is a set of tooling called Structurizr. Structurizr is part kind of
Sass product, part Open Source. In its very simplest form, you can write a simple, demanding specific language to create some diagrams. So this is really just an implementation of the people, software
systems, containers, components thing I briefly showed you before. It’s like Wes Ethan’s
diagrams if you’ve seen that. This is great for sketching
up something small and simple, a single diagram at a time, but it’s not really where we want to go. If I have an existing code base, why can’t I just auto-generate diagrams? Has anybody tried this? (laughs) What happened? You just get chaos. Is that because your code base is chaos? Sometimes, but often not. Often it’s just showing too much detail. So one of the things I’ve done
recently with Structurizr, so Structurizr’s all cloud-based and lots of my potential
customers like it, but they don’t want to send their software architecture
models up to the cloud. So I built a very simple on-premise API because Structurizr is
essentially a JavaScript app running in the browser. If you install an API that
you can reach locally, you can store the data locally. It’s about less than 1,000 lines of code. And this is what that code looks like if you auto-generate a UML
class diagram in instantly. It’s not particularly useful is it? It’s showing us all of
the code level elements and all of the relationships between them and it’s hard to really pick
out what the important parts of this code base are. And this is a really, really small app, like less than 1,000 lines of code. What happens if you point this at 100,000 or one million lines of code? You just get crazy, crazy diagrams. And the reason is that
these diagramming tools see code, not components. These diagramming tools are usually unable to zoom up to show you
bigger abstractions. It’s essentially the
model-code gap thing again. And we can trace this
problem right back in time. There was a paper about
this problem in the 90s. The first two opening
paragraphs basically say if you ask an engineer to draw a picture of their software system, you
get a nice high-level view. If you reverse engineer
a diagram from the code, you get something totally,
totally different. The reverse engineered diagram
is super accurate, of course, but it’s not how the engineer
thinks about the world. And it all comes back to this question. Well, what is a component? If I want to draw a component diagram, I need to understand what a component is. And if we go back to my
little class diagram here, these two boxes I’ve
highlighted are really what I consider to be the components in this little API app I’ve built. There’s a Java server
handling API requests and there’s a workspace
component that’s dealing with these structure of the workspaces. You’ve heard of server-less,
this is framework-less. (laughs) This is like the
simplest implementation you could possibly write. And all of these other
code things are just parts of those two components. And again, this is what the
code structure looks like. So I’ve got two major
components with a bunch of helper code, essentially. Now, we have to say that the code is the single point of truth, the code is the final embodiment of
all the architectural ideas. Can we get that information back out of an existing code base? And the answer is not really. So if you were to give me your code base, could I generate something like a context diagram automatically by looking for references to people and software systems in your code base? And the answer is no because
they don’t really exist. We don’t have this
information in our code base much of the time. The same with containers. Can I get a list of the containers just by scraping data from your code base? There’s some information
in there, but it’s kind of hard to find. When I get down to the component level, this is really the level I
want to generate automatically because it’s the most volatile and it changes the most frequently. George Fairbanks to the rescue. George Fairbanks says we should adopt an architecturally-evident coding style. Anybody doing this? You should, it’s really
a tool that’s fantastic. So it’s a really, really simple technique and it’s simply about
embedding information into your code base so that your code base reflects your architectural
ideas and intent. This sounds kind of high-level and wobbly. In concrete terms, it’s just
stuff like naming conventions. So if you have a logging component on your architectural diagram,
make sure there’s something in your code base called
logging component. Maybe it’s about a namespacing
or packaging convention. One fold or one namespace, one package per box on the diagram. Or maybe it’s machine-readable metadata, annotating stuff to be this is important, this is a component for example. And by using this we can then extract really useful information from a code base and supplement it where that
information’s not possible. And I want to move away from
drawing diagrams in Visio. There’s something called an architecture description language. I’m guessing no one’s ever heard of it and no one’s ever used it. And that’s because it’s never really entered mainstream industry, but an architecture description language is essentially a textual
description of say, the static structure of a software system. There are a bunch of them out there, Darwin or Koala for example, but the syntaxes are horrible and you have to teach developers another weird looking language
just so they can describe the piece of software
that they’re building. But this is a fantastic concept
because we’re not dealing with pictures, we’re dealing with text. And as developers we like text. We can diff text, we have
tooling to support text. So let’s take all of these
things, chuck ’em in a pot, stir it around, and come up with an architecture
description language using code, using general purpose code, the same code we’re using
to build our systems. And that’s the other piece of Structurizr, so there were two Open Source libraries and basically they are a
very small implementation of the C4 stuff. Again, there’s a bunch of classes in both, one for Java and one for .NET, and they let you create
people and software systems and containers and components
and wind them together to describe your software architecture. So that’s how we got using this for describing my little API thing. So as a user, a person. The person, the software developer’s using my Structurizr product
and Structurizr uses the API to store information locally. So again, we can just write up some code to create that little model. And then I can create
a system context view by adding the appropriate
things to my diagram. And the net result is very
simply you get a picture like this from code like this. This is a very, very
simple way to describe the high-level structures
of a software system. We go down to containers,
it’s just the same deal. So from a container perspective,
essentially all I have is a little API server, it’s
a web app, it’s a Java web app storing information on a file system. So again, we can create
a couple of containers, we wind them together just
using some method calls, and we can create some diagrams. So basically you write
code, you get pictures. This is great for the high-level stuff. Once you get down to
components, you don’t want to have to do that. So this is why the Open Source libraries have some component finder things in it. And the component finders find components. See, naming’s not hard after all. Now, the question becomes
how do you find components and the answer is it’s up to you because every code base is different. And this comes back to the
architecturally evident coding style thing. So if you have a naming convention that your team’s adopted, you
can go and find components based upon that naming convention. If you use a framework like Spring, you can go and find Spring annotations and call them components and so on and so forth. So lots of different
strategies you can plug in to find components. This is the code I use
to find the components in my little API application. Got a couple of different strategies here. I want to find the things
ending with the word servlet and I want to find the
things that I’ve annotated with my own special app
component annotation. Find them, wind them together. And actually there’s some
logic behind the scenes in the framework that goes and finds the inter-component dependencies. And that’s the sort of
diagram you get from that. So that’s the API servlet
component that it found and that’s the workspace component and it’s identified the
relationship between them. You might be wondering how
did that text get on there? And the answer is you have
to add some more metadata to your code base to do that. This is really about creating a model, so I want to get people
away from using diagrams and back to using modeling as an approach for describing software. And because once you
have a model, you can do lots of really interesting things like generate diagram keys
automatically. (cheers) No more horrible notation
we don’t understand. Because this is a model, we can do things like hyperlink the model to the code. So if you go online and
you find these diagrams, you can double-click any of the components and it takes you right to GitHub, it takes you to the exact
implementation of that thing. And again, it comes
back to the maps thing. Diagrams are maps. This is a funny tweet. 388,000 pixel wide picture. My reason for including this tweet is basically, does such an approach scale? And the answer is no
if you use it naively. So this is what happened
when I threw my own tooling at one of my own web apps. All of these things
are web app controllers and these things are components. My goodness, it’s horrible. I don’t think the code’s
horrible, the diagram’s horrible, and of course making the
diagram canvas larger does not help one bit because you still have the message, just spread out. But because this is a
model, you can do some interesting things like
don’t show me everything, show me a slice through the system. For example, we can say what’s a slice? Well, maybe it’s a slice starting
from a web app controller, an entry point to your system. And show me that slice until you drop out of the bottom of the app. So basically you can
create a larger number of much, much simpler pictures. So that’s my approach for
dealing with complexity in scale. Once you have a model, you can throw it into lots of other types of tooling. So if you’re a Graphvis fan, part of the Java Open Source library is a Graphvis exporter so it creates a DOC file, you put the
DOC file into Graphvis, it auto-generates diagrams for you. If you hook all of this stuff
up to your build process, guess what happens? Your documentation, your
diagrams remain up to date when your code changes
and that’s ultimately what I’m trying to get to here. So the title of this talk was Visualize, Document, Explore so we should talk about
documentation really quickly. A lot of people are no
longer documenting anything. I know that sounds a bit extremist. We have our friend, the Agile
Manifesto to thank for that. It people’s misinterpretation
of what the Agile Manifesto says about documentation. And of course, if I did
drop you into a project that’s unfamiliar to you, a code base that you’ve never seen before, you do get that kind of, “Where
am I on this leafy lane?” and you have to start
zooming around exploring and try to figure out where you are. And this takes time. That lane I dropped you
in right at the start, you could keep walking
until you met somebody and asked them, “Where am I? “Where’s the nearest X?” for example. But it’s just gonna take some time. Of course, once you’re
exploring the code base, the code base actually
doesn’t tell you everything you want to know. The code doesn’t tell
you the entire story, especially around things
like rational and intent. Why were these decisions made? That’s often missing from the code base. And often, teams have
lots of tribal knowledge kicking around as well,
specialists and experts in particular parts of the code base. And that’s fine until those people leave or they get run over by
the proverbial London bus. The thing is, the bus
factor as we call it, is not just about buses. Imagine you have a small team here, one does get run over by a
double-decker bus, bye-bye. Someone goes into sabbatical for a year and we have to fire somebody
because they’re useless. And now we have a smaller
team and the smaller team starts saying things like,
“You know that thing there “that we have to run
every week, what is it?” Oh, and again, that’s a
kind of extreme thing, but I have seen situations
like that occur. So how do we fix our
documentation problems? Well, we write some documentation. And this is where the SAD comes into play. And it’s called the SAD
because it makes you sad. And there are lots of templates out there for this sort of thing. Every consulting company
I have ever worked at has created their own. Rupp has one, there’s
lots of them out there. And these sort of software
architecture documents normally include some really interesting,
insightful information. How do we get to the design,
what were the design decisions, what is the architecture,
how do we look after it? These documents tend to be just horrible. Hundreds of pages. Out-of-date totally, useless. So how do we fix this? Well, it turns out naming is our friend. What I do is I just rename the document and all the problems go
away. (audience laughs) And I call it a guidebook. Like the Jersey guidebook thing
I talked about at the start. If you come to Jersey,
you buy a guidebook, it has a bunch of maps
to help you navigate an unfamiliar environment,
it shows you the sites and the itineraries,
the points of interest, the things you really should come and see. It talks about the
history and the culture. How did Jersey get to where it is today? And there’s all the practical stuff. Again, if you take that
metaphor and apply it to a software system, you get
a really, really interesting set of documentation. So maps, the diagrams, show
me what the code looks like, how do we explore the code base, which parts of the code base
are useful to understand, which parts are important
because most stuff isn’t. How did the code base
evolve to where it is today and how do we look after it? This is my single tip for documentation, just describe what you can’t
get from the code base. That’s it, it’s as simple as that. Knock it up a level of abstraction. And make these things small. Don’t have hundreds and
hundreds of pages of stuff that becomes out-of-date. Make these things as
small, lean as possible. They’re really kind of living, breathing,
evolving style documents. This isn’t the big up front design, we must create a SAD up front approach. This is a supplementary
piece of documentation that sits alongside the code base. And it’s a product-related document. A software system, a document,
a supplementary document. This doesn’t mean you can’t
do product documentation as well, but every software system should have a user guide essentially. How does the software work? (sighs) You choose, I don’t care. It’s the tooling thing and what tooling do you recommend for documents? A lot of people still
use Word, that’s fine. SharePoint if you really have to. Lots of people using Conference, but I’m seeing more and more teams at tops of things that I
ask to dock a mark down. And they’re creating a nice
little documentation files and they’re sticking
the documentation files next to the source code
in source code control. And then they do stuff at build time, generate HTML, uploading to
websites and Wikis and so on. So there’s a lot of
opportunities for using different tooling here. Again, that’s something I’m
trying to do with Structurizr. I want to create a
software architecture model that contains both the model,
the visualization stuff, and the documentation. So this is the code I wrote to document my little API application. It’s a bunch of simple mark down files, you upload it as part of the model, and some documentation’s
basically generated for you, that’s it. So again, I’m trying to keep
all of this stuff in one place. And you can also embed
diagrams in your documentation. So again, these things are
together where they belong. There are some other
approaches to documentation. So this guy’s saying lots
of really interesting stuff around living documentation,
he’s got a whole bunch of little tools, Open Source and GitHub, that you can use for
creating documentation from code, for example. And these guys in Germany have a software architecture
document they call arc42 and it’s a really, really nice,
lightweight, lean approach to documenting software systems. It’s very similar to the
approach I particularly take. And there’s lots of content,
lots of free content that you can grab on arc42. People say, “How long
should a document be?” and that’s the wrong question to ask. How many pages is the
wrong question to ask. If I join your team,
what I’m really looking for is a document I can consume in like one or two hours
over a coffee or two to get a good jump-off point into the code so that I can go and explore
in a much more structured way, much more structured manner. To speak of exploring,
once you start to model your software, you can do
some really interesting stuff with it. So you can do things like
create a JavaScript D3 visualization of the static elements, it’s just a tree structure. So this is a model that one
of the sample applications from the Spring Team, it’s
called the Spring Pet Clinic, and this is just the software
system container’s components. You can do things like let’s
find all of the interesting component dependencies, incoming
and outgoing dependencies. You can do things like
let’s rate our components based on size and complexity. So again, once you have
a model, you can do some cool stuff with it. You can throw it into Neo4j
if you really want to. Why not? The software architecture model
is just a directive graph. You throw it into Neo4j and
you can query it or cypher. People are actually doing this. There’s a whole set of
tooling called jQAssistant that let’s you do this. You run it, it gets your source code, you set up some rules and basically it pops it into Neo behind
the scenes, it’s awesome. And these guys, Empear, they’ve
created a set of tooling that runs against your
source code repositories and not only are they
doing static analysis, but they’re also super
imposing the human aspects on top as well. So they can look for things like, we have this one thing here
and it’s always changed by these two different teams, why is that? Maybe we’ve got the component
boundaries incorrect in this particular instance. So again, there’s really
cool technology there. In summary, there’s a virtual panel about software architecture
documentation from 2009. Some people you might now on
here, Eoin Woods of course, and it says things like we should be able to see the architecture in the code. We should be able to embed
this information in the code. We should be able to get the documentation from a click of a button for example. It’s really about automating as much of this documentation as possible. I don’t think we’re there yet, but I think we can get there and we are
starting to get there of course. My summary is really
that diagrams are maps. Treat your software architecture diagrams as a set of simple maps
to describe your code based on different levels of abstraction. Any documentation you
create should describe what the code doesn’t,
it’s as simple as that. And yeah, the 1990s called and
they want their tooling back. (laughs) So stop using Visio,
please stop using Visio. And if you’re gonna
say, we don’t use Visio, we use Gliffy, it’s the same thing. Stop using that as well. Stop manually drawing boxes and lines to describe software architecture. All of the tooling aside,
my final closing comment is very, very simple. Whenever you’re describing
software, make sure within your team you have a
ubiquitous language to do so. That’s me, thank you very much. (audience applauds)

GOTO 2016 • Visualise, Document & Explore your Software Architecture • Simon Brown

2 thoughts on “GOTO 2016 • Visualise, Document & Explore your Software Architecture • Simon Brown

  • June 22, 2018 at 9:56 am
    Permalink

    Well done

    Reply
  • April 24, 2019 at 6:03 am
    Permalink

    Thanks. It is a big problem that is not solved yet

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *