Common mistakes in architecture diagrams (2020)(ilograph.com)
ilograph.com
Common mistakes in architecture diagrams (2020)
https://www.ilograph.com/blog/posts/diagram-mistakes/
72 comments
> Diagrams are a communication tool. No more, no less. The vast majority aren't up-to-date, complete or even completely accurate...
In industrial process engineering, diagrams of process flow and instrumentation are literally part of "The Plan". They are included with architectural, mechanical, and electrical drawings; signed of by professional engineers and jurisdictional authorities; and passed to contractors to build. If there's a need to deviate from "The Plan", it gets documented and then a revision is created.
It has always surprised me how software as an industry gets away with sketchy documentation
In industrial process engineering, diagrams of process flow and instrumentation are literally part of "The Plan". They are included with architectural, mechanical, and electrical drawings; signed of by professional engineers and jurisdictional authorities; and passed to contractors to build. If there's a need to deviate from "The Plan", it gets documented and then a revision is created.
It has always surprised me how software as an industry gets away with sketchy documentation
I should add, Los Alamos National Labs has a great set of engineering drawing examples:
https://engstandards.lanl.gov/Dwgs_Details.shtml
https://engstandards.lanl.gov/Dwgs_Details.shtml
> It has always surprised me how software as an industry gets away with sketchy documentation
very true, the best documentation i've seen isn't even drafted until after the software is already in production.
very true, the best documentation i've seen isn't even drafted until after the software is already in production.
On the flip side, few things end up like planned.
Customers don't even know how their systems work, and only discover the edge cases they had handled in the old system when they discover it suddenly not working in the new system, and so on.
When I ask customers "does X ever happen" and they say "no, never", I now assume that means "possibly, but seldom". If I need to make sure, I drill them hard on it.
I've been in meetings where a line manager doesn't know that one of the workers they manage performs a critical business operation daily, without which the whole thing would grind to a halt. That's one level up. No wonder those who decide, many levels above that, have no idea and get it wrong.
Customers don't even know how their systems work, and only discover the edge cases they had handled in the old system when they discover it suddenly not working in the new system, and so on.
When I ask customers "does X ever happen" and they say "no, never", I now assume that means "possibly, but seldom". If I need to make sure, I drill them hard on it.
I've been in meetings where a line manager doesn't know that one of the workers they manage performs a critical business operation daily, without which the whole thing would grind to a halt. That's one level up. No wonder those who decide, many levels above that, have no idea and get it wrong.
"Agile" has only made this worse.
I mean it’s easy to pick on Agile but the reason it was introduced was because Waterfall approach clelarly didn’t work.
Unlike other kind of engineering software is much more iterative and flexible, so designing a process around this makes more sense.
Unlike other kind of engineering software is much more iterative and flexible, so designing a process around this makes more sense.
I never worked anywhere that was truly waterfall and I've been in the industry for almost 30 years. The best projects I worked on have been iterative with some sort of upfront design phase for each iteration, where an "iteration" was a large chunk... like a couple months... You might hear this referred to as the "spiral" model. There are many shades of gray between "waterfall" and true "agile" and I'd argue that neither extreme actually works.
I have been involved in numerous "waterfall" software projects and the majority were successful. This is because the "waterfall" process was never as the Agile proponents describe it. Successful "waterfall" projects are always iterative.
You know what didn't work? SAFe Agile.
You know what didn't work? SAFe Agile.
> Diagrams are a communication tool.
For me it’s primarily a tool that aides and shapes my thinking. I start sketching out diagrams to discover dependencies, edge cases, and so on. Most of what I draw I don’t share.
Even during brainstorming sessions I’ve found immense use of diagrams, they cut out so much noise.
For me it’s primarily a tool that aides and shapes my thinking. I start sketching out diagrams to discover dependencies, edge cases, and so on. Most of what I draw I don’t share.
Even during brainstorming sessions I’ve found immense use of diagrams, they cut out so much noise.
Yeah, you need know your audience and make different diagrams for different reasons and different people.
Once you come at it like “I want to teach someone this concept and have them enjoy the journey,” you’ll make ungodly good presentations :)
Once you come at it like “I want to teach someone this concept and have them enjoy the journey,” you’ll make ungodly good presentations :)
The TFA correctly lists many sins with architecture diagrams, but misses the proverbial forest over metaphorical trees.
IMO the mistakes mentioned in these diagrams stem from them actually being component diagrams disguised as architecture diagrams.
While the astute would be technically correct in calling component diagrams a type of architecture diagrams, focusing on components is what typically leads to diagraming mistakes. Component diagrams are really useful when determining what competencies, licenses/subscriptions, etc. are required when for example evaluating fit of project inside of an existing ecosystem.
However, when managing the system or making changes to it, you rarely care whether data is stored on S3 or local minio cluster, because at an interface level S3 merely a protocol. Yet, you do care about data dependencies and control boundaries.
A component diagram may easily just connect application backend to S3-compatible storage component and call it a day, however in a full architectural diagram you would really want to see where e.g. the auth thingie comes from.
IMO the mistakes mentioned in these diagrams stem from them actually being component diagrams disguised as architecture diagrams.
While the astute would be technically correct in calling component diagrams a type of architecture diagrams, focusing on components is what typically leads to diagraming mistakes. Component diagrams are really useful when determining what competencies, licenses/subscriptions, etc. are required when for example evaluating fit of project inside of an existing ecosystem.
However, when managing the system or making changes to it, you rarely care whether data is stored on S3 or local minio cluster, because at an interface level S3 merely a protocol. Yet, you do care about data dependencies and control boundaries.
A component diagram may easily just connect application backend to S3-compatible storage component and call it a day, however in a full architectural diagram you would really want to see where e.g. the auth thingie comes from.
I would say most of the examples in TFA are deployment diagrams, not (software) component diagrams. For all the flaws of UML, at least it taught us to be quite specific in which aspect of the system we are currently modelling.
The challenge is getting software engineers to learn and use UML properly. As a discipline, we seem to be in a perpetual state of reinventing the wheel, when we have plenty of mature tools and established best practices that people don't care to learn.
I have to confess I am guilty of this — I used to just draw some unstructured circles and arrows on a whiteboard and call it enough.
Lately I've been trying to work my way through lots of different diagram types from https://plantuml.com/, and it does help to wrap my mind around the existing options.
Lately I've been trying to work my way through lots of different diagram types from https://plantuml.com/, and it does help to wrap my mind around the existing options.
A related issue that we, software engineering people, ignore the design-implement workflow other engineering areas successfully use, mainly because that is not agile enoughtm.
Unless teams are bound by some ISO to have design documentation timestamped earlier than feature DoD, engineering process gets flipped on its head and design docs are quite likely to be simply braindumps of some uninterested party rather than formal-ish specifications driving the implementation.
> when we have plenty of mature tools and established best practices that people don't care to learn.
Hyper-fixation on agile and "move fast and break things" attitude is in part to blame here. You can't really put a timebox on "learn how to use mature tooling" or storypoint "design architecture", when only implementation is rewarded.
Unless teams are bound by some ISO to have design documentation timestamped earlier than feature DoD, engineering process gets flipped on its head and design docs are quite likely to be simply braindumps of some uninterested party rather than formal-ish specifications driving the implementation.
> when we have plenty of mature tools and established best practices that people don't care to learn.
Hyper-fixation on agile and "move fast and break things" attitude is in part to blame here. You can't really put a timebox on "learn how to use mature tooling" or storypoint "design architecture", when only implementation is rewarded.
There’s truth in what you say and UML has some good ideas, but it’s not the one true way. One problem with it is that even if engineers can read it properly, diagrams often need to do several jobs at once, and communicate something to non-engineers, otherwise you are making diagrams all day!
The various times I've encountered effective UML, it's been an organization's take on how to use it. I can't remember if the UML Distilled book references this kind of dialectic use but it seems like the only way I've seen buy-in for use and maintaining the diagrams as documentation.
> That said, you probably don’t want to be making theoretical architecture diagrams most of the time.
My take on this is that it's really hard to have one diagram to rule them all. I think there's a time and a place for different kinds of diagrams, and I think it's ok to tell a story with a couple different ones. For example, a conceptual diagram that complements the actual "as implemented" diagram. One is a big of a "here's what we were thinking" and the other is "here's how we translated that to actual architecture".
In my role of frequently having to manage up to executive management, investors, onboard new people, etc. the combination of conceptual plus actual is powerful. I can describe the problem we're solving, provide a grokkable format for most levels of the org chart, and then have the details for those who want to dig in to discuss how we built (or plan to build) it and why.
My take on this is that it's really hard to have one diagram to rule them all. I think there's a time and a place for different kinds of diagrams, and I think it's ok to tell a story with a couple different ones. For example, a conceptual diagram that complements the actual "as implemented" diagram. One is a big of a "here's what we were thinking" and the other is "here's how we translated that to actual architecture".
In my role of frequently having to manage up to executive management, investors, onboard new people, etc. the combination of conceptual plus actual is powerful. I can describe the problem we're solving, provide a grokkable format for most levels of the org chart, and then have the details for those who want to dig in to discuss how we built (or plan to build) it and why.
And then you have the diagram evolution cycle:
Step 1: People want a simple high level architecture diagram. Step 2: People want more detail Step 3: People want to see how human components of the system work Step 4: The diagram is so complicated and non-obvious that people start asking for a simpler high level architecture diagram.
The only way to escape is to be clever about preserving multiple 'zoom' /C4 levels of diagram.
Step 1: People want a simple high level architecture diagram. Step 2: People want more detail Step 3: People want to see how human components of the system work Step 4: The diagram is so complicated and non-obvious that people start asking for a simpler high level architecture diagram.
The only way to escape is to be clever about preserving multiple 'zoom' /C4 levels of diagram.
> The only way to escape is to be clever about preserving multiple 'zoom' /C4 levels of diagram.
Fully agree. Having gone through startup funding rounds and acquisitions, that's the set of diagrams that I have ready or prepare for each one. The "suits" like the higher level stuff, while the people digging into technical due diligence or post-acquistion integration like the more detailed ones. They're also adaptable at many levels for any domain-specific "enhancements" that are necessary, such as a data flows, security flows, and the like.
Fully agree. Having gone through startup funding rounds and acquisitions, that's the set of diagrams that I have ready or prepare for each one. The "suits" like the higher level stuff, while the people digging into technical due diligence or post-acquistion integration like the more detailed ones. They're also adaptable at many levels for any domain-specific "enhancements" that are necessary, such as a data flows, security flows, and the like.
I often think of Marr's "three levels of analysis" from cognitive neuroscience when thinking about technical communication and different audiences.
there's the "computational level" (poorly-named, focused on high-level objectives of the system), algorithmic level, and implementational level.
works for understanding any information processing system, not just brains/minds as he originally planned
there's the "computational level" (poorly-named, focused on high-level objectives of the system), algorithmic level, and implementational level.
works for understanding any information processing system, not just brains/minds as he originally planned
> For example, a conceptual diagram that complements the actual "as implemented" diagram. One is a big of a "here's what we were thinking" and the other is "here's how we translated that to actual architecture".
It maybe could have been clearer in the article, but the intent wasn't to discourage "here's what we were thinking"-style whiteboard diagrams. Those absolutely have their place. The article is trying to discourage people from making "here is how Kubernetes works" or "here is how microservices work" diagrams, since you can easily find those online.
It maybe could have been clearer in the article, but the intent wasn't to discourage "here's what we were thinking"-style whiteboard diagrams. Those absolutely have their place. The article is trying to discourage people from making "here is how Kubernetes works" or "here is how microservices work" diagrams, since you can easily find those online.
Exactly! Several different sorts of folks have an interest in product architecture, and each group needs the story told at a different level of abstraction. So inevitably one has to maintain a few different flavours of the diagram and associated story.
One way I think of it is that the architect needs to market the architecture, at least a little bit. If you ask a marketing team to deliver a message they immediately start crafting multiple delivery methods to meet people where they are at. Architects shouldn't think they can somehow escape that basic requirement of effective communication.
One way I think of it is that the architect needs to market the architecture, at least a little bit. If you ask a marketing team to deliver a message they immediately start crafting multiple delivery methods to meet people where they are at. Architects shouldn't think they can somehow escape that basic requirement of effective communication.
Code architecture, component architecture, physical architecture as fully deployed. Data architecture. The design of adding ljkely new features. So many things to decide and communicate. So many presentations with at best one thing explained.
This is a nice run through of some pitfalls. I'd love to see an accompanying "how to make a great architecture diagram", I think the purpose behind these diagrams often gets lost (or was bad to start with) and as a result I've seen (and probably produced) a lot of unhelpful architecture diagrams.
Being cynical, I've seen some that clearly attempt to overcomplicate things in order to convey something along the lines of "look at all this complexity we're managing, aren't we great?". Might be useful for getting your team some additional credit, but less helpful in a few years time when somebody is trying to use the diagram to figure out the underlying structure of things.
Being cynical, I've seen some that clearly attempt to overcomplicate things in order to convey something along the lines of "look at all this complexity we're managing, aren't we great?". Might be useful for getting your team some additional credit, but less helpful in a few years time when somebody is trying to use the diagram to figure out the underlying structure of things.
> This is a nice run through of some pitfalls. I'd love to see an accompanying "how to make a great architecture diagram", I think the purpose behind these diagrams often gets lost (or was bad to start with) and as a result I've seen (and probably produced) a lot of unhelpful architecture diagrams.
Naturally I think you'd go a long way just avoiding these pitfalls and doing the reverse (e.g. label your arrows). For a somewhat different perspective on making good diagrams by reducing their complexity, I wrote on this just last month:
[0] https://www.ilograph.com/blog/posts/breaking-up-the-master-d...
Naturally I think you'd go a long way just avoiding these pitfalls and doing the reverse (e.g. label your arrows). For a somewhat different perspective on making good diagrams by reducing their complexity, I wrote on this just last month:
[0] https://www.ilograph.com/blog/posts/breaking-up-the-master-d...
> Might be useful for getting your team some additional credit, but less helpful in a few years time when somebody is trying to use the diagram to figure out the underlying structure of things.
I'm pretty sure people that aim for the former actually like the latter too
I'm pretty sure people that aim for the former actually like the latter too
I’m surprised no one has mentioned the C4 approach to diagramming yet, which is a prescriptive approach that helps to avoid most of these mistakes: https://c4model.com/
An important caveat is that C4 is narrowly tailored to monolithic software systems. When diagramming cloud or (micro-)service systems, its prescribed abstractions start to work against you. For example, there is no appropriate level for (e.g.) VPCs, virtualized containers, or abstract concepts like microservices. At that point, you’re left either abandoning C4 or debating with everyone about the exceptions you have to make to make it fit.
c4 has a deployment extension, fyi.
https://c4model.com/diagrams/deployment
that being said I consider that an implementation detail.
https://c4model.com/diagrams/deployment
that being said I consider that an implementation detail.
> C4 approach to diagramming
This highlights my only beef with TFA, since it seems to go against the advice to not mix abstraction levels.
TFA is great advice for getting at least mediocre diagrams, informative and inoffensive. But the best diagrams are deliberately mixing levels to highlight stuff, because layer boundaries are usually where it gets tricky. Maybe none of this is relevant if you really want to split hairs about what architecture vs system vs component diagram “really” means, but I’m not aware of nonfuzzy definitions for that and most people seem to use the terms informally.
This highlights my only beef with TFA, since it seems to go against the advice to not mix abstraction levels.
TFA is great advice for getting at least mediocre diagrams, informative and inoffensive. But the best diagrams are deliberately mixing levels to highlight stuff, because layer boundaries are usually where it gets tricky. Maybe none of this is relevant if you really want to split hairs about what architecture vs system vs component diagram “really” means, but I’m not aware of nonfuzzy definitions for that and most people seem to use the terms informally.
There is some interesting new working the C4 space at https://likec4.dev/
This is a less prescriptive model than structurizr but keeps the goals of C4
This is a less prescriptive model than structurizr but keeps the goals of C4
Most software architecture diagrams are a mess ... partly due to ad hoc notation, and partly because it's very unclear what the boxes represent. C4 resolves the latter problem by introducing a small number of predefined abstractions. This sounds limiting, but the power of C4 is that limited set of abstractions, and the conversations it forces architects/developers to have.
The less prescriptive approach of LikeC4 sounds very appealing, because it provides a way to define your own abstractions. But I don't recommend this approach for most teams -> https://c4model.com/abstractions/faq#can-we-add-more-abstrac...
The less prescriptive approach of LikeC4 sounds very appealing, because it provides a way to define your own abstractions. But I don't recommend this approach for most teams -> https://c4model.com/abstractions/faq#can-we-add-more-abstrac...
My personal rule of thumb is that every diagram that shows more than a couple of AWS icons is likely useless.
First of all, something like 99% of the AWS icons are illegible. You just don't know what they refer to.
Second, if it has a couple of AWS icons it likely has like a hundred of them, connected with arrows in an indecipherable mess.
I personally try to simplify diagrams as much as possible and prefer to talk about function (e.g. DB, App Server) more than technology (e.g. Aurora, Java), but the key element here is to try to avoid trying to put too much dense information in a single diagram which it ends making it very confusing.
First of all, something like 99% of the AWS icons are illegible. You just don't know what they refer to.
Second, if it has a couple of AWS icons it likely has like a hundred of them, connected with arrows in an indecipherable mess.
I personally try to simplify diagrams as much as possible and prefer to talk about function (e.g. DB, App Server) more than technology (e.g. Aurora, Java), but the key element here is to try to avoid trying to put too much dense information in a single diagram which it ends making it very confusing.
I’d extend it to any icons, not just AWS ones. I agree usually the generic technology is more interesting than the semantic thing. Icons in architecture diagrams are distracting noise. They might be okay if they were smaller, but usually they’re huge and overpower the text.
I find the article falls in its own pitfall of justifying every section with "it's hard / misleading for a new joiner / beginner".
I almost never do architecture diagrams for new joiners or beginners, I do them for the other experts of my team, and they perfectly understand that subscriptions go in the Subscription table in DDB because they've all worked on this system.
A lot of those points go against probably the most important point "Too many overlapping concerns".
The point of a diagram is to get a point across, and I don't believe there's any universal rule that will make this easier, because there's no universal audience.
I almost never do architecture diagrams for new joiners or beginners, I do them for the other experts of my team, and they perfectly understand that subscriptions go in the Subscription table in DDB because they've all worked on this system.
A lot of those points go against probably the most important point "Too many overlapping concerns".
The point of a diagram is to get a point across, and I don't believe there's any universal rule that will make this easier, because there's no universal audience.
I joined a company a few years ago, and there was a long term dev that had been there forever and was now a manager and did live trainings on webex with Lucid chart, where there was no prepared docs or whatever, but he drew the architecture diagram as the training, providing detailed explanations and answering questions as the diagram went. It was astonishingly effective at getting the points driving the architecture (and the salient business context driving the architecture). Each detail and each big overarching principal stuff would come at at the time when its context was right there on the evolving diagram. i was so inspired I bought a Lucid subscription, tho I never have done such good presentations, having some pictures I find makes it easier to communicate with more people.
I would like to see a before and after.
For example, #3 too many concerns. The author states "the solution is to split up a busy diagram into multiple diagrams, each focused on one or two concerns at a time" . I understand that but is there a diagram that ties all the smaller diagrams together without re-creating the original diagram in the first place?
For example, #3 too many concerns. The author states "the solution is to split up a busy diagram into multiple diagrams, each focused on one or two concerns at a time" . I understand that but is there a diagram that ties all the smaller diagrams together without re-creating the original diagram in the first place?
Hi, author here. When I re-read this (it's from 2020) I had the same thought and wrote up an extended example of this just last month: https://www.ilograph.com/blog/posts/breaking-up-the-master-d...
Thank you for posting the follow up
I always have both. It is VERY hard for people to understand how the system is actually working if you just include a bunch of diagrams separated by concerns without some kind of atlas/globe level diagram that shows how they fit into the overall puzzle.
That makes sense.
On topic, anyone know of a repository or collection of nice architecture diagrams out there?
There's a small asterisk to your question: there's no way to verify that the diagrams represent the underlying system without access to the code (and sometimes the deployment). Anyone can make pretty pictures without spaghetti lines, but it takes some real, no kidding, discipline to write code (and then deploy that code) in a non-spaghetti way
It's like that phrase "no plan survives first contact with the enemy" but applied to product owners and then subsequently applied to computers
It's like that phrase "no plan survives first contact with the enemy" but applied to product owners and then subsequently applied to computers
100% correct. The only ones which had both a repo and a diagram that I've consistently found were AWS sample architectures. Their diagrams are usually pretty lacking, though: https://www.ilograph.com/blog/posts/better-aws-architecure-d...
This is, of course, extremely subjective, but I find myself using this slide deck from Google Cloud (https://docs.google.com/presentation/d/1fD1AwQo4E9Un6012zyPE...) as inspiration and/or to see how others design their diagrams.
Not a repo but I remember a book titled something like "architecture in 500 lines or less" that had really pretty explanations and diagrams
Was it this one: https://github.com/aosabook/500lines ?
I keep seeing such diagram, keep people making and presenting them, and I'm not sure if it's just me or they are generally counterproductive?
Let's the take one from #5 in the article. If someone instead of painting this diagram wrote: "Drupal Load Balancer inside Drupal VPC load-balances traffic between Drupal Instances inside two Availability Zones: AZ1 and AZ2" it's way faster to read, more precise, and leaves me without a doubt that I misunderstood or missed some detail.
It's even worse on more complex and busy diagrams. Takes me a while to just visually parse everything, figure out relations between elements, arrows, and even after I scan everything I'm not sure if I understood everything.
On top of it, just creating and later maintaining them is such a hassle, comparing to just editing text.
Let's the take one from #5 in the article. If someone instead of painting this diagram wrote: "Drupal Load Balancer inside Drupal VPC load-balances traffic between Drupal Instances inside two Availability Zones: AZ1 and AZ2" it's way faster to read, more precise, and leaves me without a doubt that I misunderstood or missed some detail.
It's even worse on more complex and busy diagrams. Takes me a while to just visually parse everything, figure out relations between elements, arrows, and even after I scan everything I'm not sure if I understood everything.
On top of it, just creating and later maintaining them is such a hassle, comparing to just editing text.
When you have a tree, text description is usually easy enough to follow
When you have a graph your text starts to look closer to an adjacency list and is utterly miserable to actually track a sequence you’re actually interested in, unless every interesting sequence is enumerated in turn
Like #4 in TFA is visually a mess, but easy enough to find & focus a single pathway. textually you’d be jumping up and down paragraph descriptions trying to stay on topic (not unlike following code itself, with no debugger/ide support)
When you have a graph your text starts to look closer to an adjacency list and is utterly miserable to actually track a sequence you’re actually interested in, unless every interesting sequence is enumerated in turn
Like #4 in TFA is visually a mess, but easy enough to find & focus a single pathway. textually you’d be jumping up and down paragraph descriptions trying to stay on topic (not unlike following code itself, with no debugger/ide support)
Looking at the graphics is much easier than understanding the text for me.
If I read the text I essencially have to build that graphic inside my mind, if I want to understand and remember it.
When I do architecture diagrams (not that often), my audience is usually non-technical people. I personally rarely see value in them, because they tend to blur different levels of abstractions as well as current and anticipated realities. I can't remember when I saw one and thought it was a useful tool to understand a system.
For story telling, they're sometimes useful to me.
For story telling, they're sometimes useful to me.
My feeling is that most such diagrams are used for purely aesthetic purposes. They break up dense text and add some color and variety to a document. They can also provide some vague feedback to a reader on whether they understood the text and, perhaps, whether they correctly understood which parts of the text are important.
So: do you need labels on errors? Answer: Yea, if they look good, otherwise no.
So: do you need labels on errors? Answer: Yea, if they look good, otherwise no.
> My feeling is that most such diagrams are used for purely aesthetic purposes. They break up dense text and add some color and variety to a document.
Not true. Many folks are visual learners. And if you're experienced enough, you can pick up the gist of the text from a quick glance at a good diagram, figure out the "shady" areas, and then dive into the text for details.
Not true. Many folks are visual learners. And if you're experienced enough, you can pick up the gist of the text from a quick glance at a good diagram, figure out the "shady" areas, and then dive into the text for details.
I get the most value out of diagrams that are fast to create during conversations, and largely ephemeral. A tool for sharing understanding, not a resource to be shared widely for long periods of time. I'll often draw very similar diagrams multiple times for different audiences. So the emphasis is very much not on getting it right/perfect, but adapting it for the audience and the moment.
Otherwise if you need something static, I don't know a way around it other than a tool that is capable of understanding a large distributed system - both deployment and codebase - and will auto-regenerate as the code and deployment system changes. In many organizations, the people skilled at diagramming aren't the people that are in the sprints making changes that will slowly break your diagrams over time.
Otherwise if you need something static, I don't know a way around it other than a tool that is capable of understanding a large distributed system - both deployment and codebase - and will auto-regenerate as the code and deployment system changes. In many organizations, the people skilled at diagramming aren't the people that are in the sprints making changes that will slowly break your diagrams over time.
Some wisdom.
But as usually everything depends on the target audience and the actual occasion.
I often make architecture diagrams for non-technical users so that we have a shared image to talk about and use as a point of reference during a discussion.
But as usually everything depends on the target audience and the actual occasion.
I often make architecture diagrams for non-technical users so that we have a shared image to talk about and use as a point of reference during a discussion.
A point that trips me up on so many diagrams is that they don't seem to have a direction to be read in. Either left to right, top to bottom, or reversed. Sometimes it can make sense to have a loop, so top is left to right, and bottom is right to left. But in all cases, have a reason for something to be where it is.
Of course, then there are the odd "maps" that people love to have to show isolated concerns, but there is no real meaning on how the map is traversed. I find these neat artistically, but they don't actually communicate that much to me.
Of course, then there are the odd "maps" that people love to have to show isolated concerns, but there is no real meaning on how the map is traversed. I find these neat artistically, but they don't actually communicate that much to me.
90% of diagrams I make exist only because someone asked me to make a diagram. IMO they're only suited for presentations.
Same. They're generally "not useful" for any practical purpose. But they look nice to a higher level audience that does not require much technical understanding. "These guys drew a diagram, they must know what they're doing", right?
These are all expository diagrams. Second-hand and auxiliary by nature.
Diagrams can be authoritative, and the ones I’ve seen will break some or all of these rules because they represent natural heuristics that practitioners are expected to fill inn themselves.
Diagrams can be authoritative, and the ones I’ve seen will break some or all of these rules because they represent natural heuristics that practitioners are expected to fill inn themselves.
My biggest gripe with architectural diagrams is when it is not clear what arrows do or when it's easy to assume that arrows do more than one thing even though they all have the same style / design and no convenient label nor legends .
Call me cynical but I suspect a lot of "errors" and "mistakes" in architectural diagrams are done on purpose so as to communicate specific points or to emphasize a certain perspective.
This is a good list of don'ts, but it would be more helpful to have a list of do's and some examples.
One that I see is commonly misconstrued is having a user stick figure going to DNS and DNS going to the app.
Why is "DNS" in the diagram in the first place? That seems like too low level a concern. You may as well have TCP and IP there.
In general I agree. Sometimes, when diagraming DNS cutover and failover strategies, it is applicable.
I'd add
- arrows with labels that are not "pronouncable". ie "A 'is a' B"
- double-headed arrows
- arrows with labels that are not "pronouncable". ie "A 'is a' B"
- double-headed arrows
I hate these low resolution images which contain text
And yet they don't show examples of good ones and why they are good.
well, how dare to show a mistake without the actual good thing to do? :D
What a diagram really needs is a purpose. A clear need for the information to be conveyed.
Who's to say that unlabeled arrows are a bad thing? Or that there's too much on a diagram? That depends on how it's used! What it's for.
Adding context and explainers is certainly a Good Thing, but again, without an overarching reason for the diagram to even exist - who cares?
Diagrams are a communication tool. No more, no less. The vast majority aren't up-to-date, complete or even completely accurate; for the same reason roadmaps aren't, let alone the map of the London Underground.