If you've ever visited a project on GitHub (for instance) with the intention of understanding how it fits into a larger system, you'll recognise the sigh of relief you experience when you find a diagram or two on (or easily reached from) the initial landing page. This is an article about the importance of architecture and specifically about the importance of diagrams.
I'm a strong open source advocate, but source code isn't enough to make a successful project, or even, I would add, to be a truly open source project: Your documentation should not just be available to everybody, but accessible to everyone. If you want to get people involved, providing a way in is vital.
Beyond that, I think we have a responsibility (and opportunity!) towards diversity in open source. Providing diagrams helps address (at least!) four types of diversity:
- People whose first language is not the same as that of your main documentation
- People who have problems reading lots of text (e.g., those with dyslexia)
- People who think more visually than textually (like me!)
- People who want to understand your project from different points of view (e.g., security, management, legal)
This article came about after I attended a virtual demo recently. The demo didn't work, but none of us was stressed by that: it was an internal demo, and these things happen. It's a place we're all familiar with, and we all felt for the project's team lead (who was presenting the slide deck) when, a few slides in, a message popped up on her screen from one of her team members saying "Demo NO GO!"
After apologising, she asked if we wanted to bail completely or just discuss the information they had on hand. We opted for the latter—after all, most demos that aren't foregrounding user experience components don't show much beyond terminal windows, at least more than most of us could fake in half an hour or so anyway.
Luckily, the members of the team presenting the demo had lots of information about what it would have shown us and a particularly good architectural diagram to discuss, so we had a productive session in spite of the problems with the demo. She answered a couple of questions, and then I piped up with one about security.
This article could have been about the security failures in a project that was showing an early demo: another example of security being left until late (often too late) in the process, when it's difficult and expensive to integrate. However, it was clear that the team had given thought to specific aspects of security, both on the network (in transit) and in storage (at rest). Although there was probably room for improvement (and when isn't there?), a team member messaged me more documentation during the call that allowed me to understand some of the choices the team made.
What this article is about is the fact that we were able to have a discussion at all. The slide deck included an architecture diagram showing all of the main components with arrows showing the direction of data flows. It was clear and colour-coded to show the provenance of the different components—which components were sourced from external projects, which were from internal projects, and which were new to this demo. The people on the call—all technical—were able to see at a glance what was going on, and the team lead providing the description had a clear explanation for the various flows. Her team members chipped in to answer specific questions or to provide more detail on particular points. This is how technical discussions should work, and there was one thing in particular that pleased me (beyond the fact that the project had thought about security at all!): there was an architectural diagram to discuss.
There are not enough security experts in the world to go around, which means that not every project has the opportunity to get every stage of its design pored over by a member of the security community. But when it's time to share, a diagram is invaluable. I hate to think about the number of times I've been asked to look at a project to give my thoughts about its security aspects and found that all that's available is a mix of code and component documentation, with no explanation of how it all fits together and, worse, no architecture diagram.
When you're building a project, you and your team are often so into the nuts and bolts that you know how it all fits together and can hold it in your head or describe the key points to a colleague. The problem comes when someone needs to ask questions of a different type or review the architecture and design from a different slant. A picture—an architectural diagram—is a great way to educate external parties (or new members of the project) about what's going on at a technical level. It also has a number of extra benefits:
- It forces you to think about whether everything can be described in this way.
- It forces you to consider levels of abstraction and what should be shown at what levels.
- It can reveal assumptions about dependencies that weren't previously clear.
- It is helpful to show data flows between the various components.
- It allows for simpler conversations with people whose first language is not that of your main documentation.
To be clear, this isn't just a security problem—the same goes for other non-functional requirements, such as high-availability, data consistency, performance, or resilience—but I'm a security guy, and this is how I experience the issue. I'm also aware that I have a very visual mind, and this is how I like to get my head around something new. But even for those who aren't visually inclined, a diagram at least offers the opportunity to orient yourself and work out where you need to dive deeper into code or execution. I also believe that it's next to impossible for anybody to consider all the security implications (or any of the higher-order emergent characteristics and qualities) of a system of any significant complexity without architectural diagrams. And that includes the people who designed the system because no system exists on its own (or there's no point to it), so you can't hold all of those pieces in your head for any length of time.
I've written before about the book Building Evolutionary Architectures, which does a great job of helping projects think about managing requirements that can morph or change priority. Unsurprisingly, the book makes much use of architectural diagrams. Enarx, a project with which I'm closely involved, has always had lots of diagrams, so I'm aware that there's an overhead involved here, both in updating diagrams as designs change and in considering which abstractions to provide for different consumers of our documentation, but I truly believe that it's worth it. Whenever we introduce new people to the project or give a demo, we ensure that we include at least one diagram (and often more), and when we get questions at the end of a presentation, they are almost always preceded with a phrase such as, "could you please go back to the diagram on slide x?"
I urge you to create diagrams, both for your benefit and also for anyone who's going to be looking at your project in the future. It's a key part of being an open project—the opening of the architecture means that the code, and therefore the project itself, becomes more accessible and more open to the wider community. Members of the community will appreciate it (and so should you). Your diagrams don't need to be perfect. But they do need to be there.
9 Comments