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

(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)