If you're working on an agile software development team at the moment, take a look around at your environment. Whether it's physical or virtual, there's likely to be a story wall or Kanban board in order to visualise the work remaining to be started, in progress and done.
Why? Put simply, it's a fantastic way of introducing transparency into software projects because anybody can see, at a glance, a snapshot of the current progress at a high-level. Couple this with value stream mapping and you can start to design some pretty fancy looking Kanban boards to reflect that way that your team works. In a nutshell, we've become pretty adept at visualising our software development process.
However, it seems we may have forgotten how to visualise the actual software that we're building. I'm not talking about post-project documentation here (that's a story for another day), I'm talking about communicating "the big picture". Why is this important? Well, if you want to ensure that everybody is contributing to the same end-goal, you need to be able to communicate the vision of what it is you're building. And if you want agility and the ability to move fast, you need to do this effectively and efficiently. You can argue about whether notations such as UML offer an effective way to communicate software architecture or not, but that's often irrelevant as a starting point because many teams have already thrown out UML or simply don't know it. What's the result? Usually boxes and lines diagrams like the sketches below.
Boxes and lines diagrams *can* work very well, but there are many pitfalls associated with sketching software architecture in this way. My approach is to use a collection of simple diagrams, each showing a different level of abstraction.
All of my guidance around doing this is going to be enhanced and included in my software architecture e-book but if you can't wait, you can always join me at Skills Matter in London (23rd April) or Bouvet in Oslo (26th April) for our Software Architecture for Developers training course.
Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.
You can find Simon on Twitter at @simonbrown ... see simonbrown.je for information about his speaking schedule, videos from past conferences and software architecture training.
One of the challenges is not only capturing the software design (which is difficult in retrospect from a codebase) but maintenance as it changes. I think a good metric for how well visualised the project is, is how long it takes to bring a new team member up to speed and productivity. If team members are still not productive after a couple of months (I've worked on projects like this) then you have an issue!