Common mistakes in architecture diagrams (2020)

201 点作者 billyp-rva3 个月前

24 条评论

bux933 个月前

The author got very close, but missing the forest for the trees.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.

评论 #43004272 未加载

评论 #43002968 未加载

评论 #43002947 未加载

friendzis3 个月前

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.

评论 #42998539 未加载

fatnoah3 个月前

> 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.

评论 #43000574 未加载

评论 #43002181 未加载

评论 #43000825 未加载

评论 #43000902 未加载

评论 #43003687 未加载

benrutter3 个月前

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.

评论 #43000063 未加载

评论 #42998928 未加载

greymalik3 个月前

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: <a href="https://c4model.com/" rel="nofollow">https://c4model.com/</a>

评论 #43000656 未加载

评论 #43000724 未加载

评论 #43003148 未加载

jaimebuelta3 个月前

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.

评论 #43000001 未加载

iLoveOncall3 个月前

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.

评论 #43003823 未加载

fm26063 个月前

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?

评论 #43000084 未加载

评论 #42999690 未加载

potamic3 个月前

On topic, anyone know of a repository or collection of nice architecture diagrams out there?

评论 #43001631 未加载

评论 #43000434 未加载

评论 #43002015 未加载

评论 #42998467 未加载

dpc_012343 个月前

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.

评论 #42998312 未加载

评论 #42998209 未加载

评论 #42997986 未加载

staunton3 个月前

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.

评论 #43002873 未加载

tunesmith3 个月前

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.

Garlef3 个月前

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.

taeric3 个月前

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.

anal_reactor3 个月前

90% of diagrams I make exist only because someone asked me to make a diagram. IMO they're only suited for presentations.

评论 #43001153 未加载

enord3 个月前

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.

racl1013 个月前

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 .

rmah3 个月前

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.

theonlyjesus3 个月前

This is a good list of don'ts, but it would be more helpful to have a list of do's and some examples.

illusive40803 个月前

One that I see is commonly misconstrued is having a user stick figure going to DNS and DNS going to the app.

评论 #43001267 未加载

ThouYS3 个月前

I'd add- arrows with labels that are not "pronouncable". ie "A 'is a' B"- double-headed arrows

_s_a_m_3 个月前

I hate these low resolution images which contain text

mrichman3 个月前

And yet they don't show examples of good ones and why they are good.

renecito3 个月前

well, how dare to show a mistake without the actual good thing to do? :D