[HN Gopher] Architecture diagrams enable better conversations
___________________________________________________________________
Architecture diagrams enable better conversations
Author : mooreds
Score : 173 points
Date : 2023-08-22 14:01 UTC (8 hours ago)
(HTM) web link (www.unravelled.dev)
(TXT) w3m dump (www.unravelled.dev)
| ShadowBanThis01 wrote:
| An article about diagrams that doesn't show a single one. Huh.
| flarg wrote:
| I know I'm old guard but uml worked well for me.
| taeric wrote:
| I'd love to see some examples. I know that the article mentions
| this as a downside of C4 diagrams, so consider this a plea to
| action from folks. I'd love to see examples of how these help.
|
| On the onboarding story, I'm specifically curious how/why
| diagrams work more than a bulleted list and other conventions
| could already do? What are the entry points? Is there a
| convention on how entry points are named? If not, why not?
|
| I love the idea of having a diagram that works as a reflection of
| the codebase. Hard not to think of ways that can help. I'm always
| worried that too much effort goes into the reflection, though.
| Especially when it is front loaded in the effort.
| gav wrote:
| I believe that one of the big things that diagrams help with is
| maintaining state while having a conversation. You don't have
| to keep track of so many things in your head and it works in a
| similar way to the "tell 'em what you're gonna tell 'em, tell
| 'em, and then tell 'em what you've told 'em" style of
| presenting--your audience gets to see up front what journey you
| are taking them on.
|
| There's a great book by Abby Covert about diagrams in general:
| "Stuck? Diagrams help."[1]
|
| From a learning perspective, having multimodal[2] options, such
| as a mix of visual (diagrams), reading, and videos/audio can
| really help with onboarding. Different people learn better with
| different methods, and different methods work better in
| different contexts, for example I personally hate sitting at my
| desk watching a video, but enjoy doing so on my phone while
| commuting.
|
| [1] https://abbycovert.com/stuck/ [2]
| https://www.learnupon.com/blog/multimodal-learning/
| stetrain wrote:
| Definitely agreed. I have found diagrams, and tools that let
| me edit them quickly, to be great "state trackers" in design
| and planning meetings. You can get consensus, keep track of
| the decisions that were made, and then have a shared model
| you can use to coordinate building that plan.
|
| This has value even if the diagram is immediately obsolete
| and discarded once the project is complete.
| kzhen wrote:
| Hi taeric, author of the article here
|
| > On the onboarding story, I'm specifically curious how/why
| diagrams work more than a bulleted list
|
| the point I was trying to make in the article was that having a
| visual representation helps new developers to build up a mental
| model of the different components of a software system. In my
| particular case the system in question is made up of: 2xAPI,
| 2xEvent Processors, Event Producer as well as dependencies on
| external systems. The architecture diagrams are helpful here as
| the new developers are able to see the interactions between
| components.
|
| > I love the idea of having a diagram that works as a
| reflection of the codebase.
|
| In C4 there are 4 levels, the first is the system view this
| doesn't bear much resemblance to the codebase, the second is
| the container level, this is where you show the different
| components that make up a system. It's important to note here
| that a component is a deployable "thing", e.g. an API,
| database, powershell/bash script etc. This is where you start
| to see a bit more of a link between the architecture diagrams
| and the codebase. My experience of level 3 and level 4 where
| you start to model the actual codebase didn't bear much fruit
| and there are tools which can do a good enough job here from
| scanning the code (particularly in the dotnet world, NDepend
| does a brilliant job, although PSPSPSs)
| taeric wrote:
| I didn't say it directly, but thanks for the article!
|
| My question is probably more asking exactly how/why the
| visual representation helps. I am very open to the idea that
| they do. But I'm also open to the idea that it is the active
| interaction with others that is the important part. That it
| is done with text or with drawings feels secondary. Almost
| distantly.
|
| Your point about the really high level views of 1 and 2 in
| the levels feels notable. I also really resonate with the
| idea of identifying the deployable "things" that can be
| independently reasoned about. If you have a team that is
| pushing libraries between the two things, you then have to
| expand this discussion to the build and deploy systems as
| being integral to your team, not merely secondary
| considerations.
| ewi_ wrote:
| I believe that the way we represent information is key to
| understanding. Data points in a list are usually way less
| insightful than a good graph (emphasis on good). What I
| have found is that it's the case in describing system
| architecture as well.
|
| As you say, you can describe a system in a few paragraphs,
| explaining the relationship between the main components.
| However, as paragraphs it can harder to grok, and also
| harder to write with no ambiguity.
|
| Now, part of what I say above can be seen as personal
| preference (text vs image), but in practice I have found
| that when using tools like plantuml or mermaid to make C4
| diagrams, the result is easier to use, remember, and update
| than plaintext.
| taeric wrote:
| I think I mostly just disagree, here. I want a graphical
| representation to be more impactful. But typically any
| system that scales such that a short list can't explain
| entry points and dependencies has scaled beyond what
| graphical tools can do, as well.
|
| Now, story boarding a communication sequence between
| systems can make great use of layout. So, I definitely
| see potential.
| jhund wrote:
| I've been using https://structurizr.com/ to automatically
| generate C4 diagrams from a model (rather than drawing them by
| hand). It works well with the approach for written documentation
| as proposed in https://arc42.org/. It's very easy to embed a C4
| diagram into a markdown document.
|
| The result is a set of documents and diagrams under version
| control that can be rendered using the structurizr documentation
| server (for interactive diagrams and indexed search).
|
| I also use https://d2lang.com/ for declarative diagrams in
| addition to C4, e.g., sequence diagrams and
| https://adr.github.io/ for architectural decision records. These
| are also well integrated into structurizr.
| rammy1234 wrote:
| I use MermaidJS for flow chart and Sequence diagram. They have
| C4 in beta. I tried and it is hard adjust the layout and many
| features are not supported for C4 yet.
|
| Visual Studio has good support for MermaidJS.
| https://mermaid.js.org/intro/
| FearNotDaniel wrote:
| I think you mean Visual Studio _Code_. Completely separate
| product. Not your fault of course, but the geniuses at
| Microsoft who gave the same name to two different IDEs in an
| environment where users of the second one are very unlikely
| to be aware of the existence of the first. Still, it's an
| important distinction worth knowing about because they have
| their own distinct extension ecosystems that are not mutually
| compatible.
| rammy1234 wrote:
| for C4 structurizr is the best so far I know. I use that for
| landscape , container diagrams. I got feedbacks that even
| CIOs are able to get the picture easy. If they have some ways
| to produce better layouts for large landscape it would be
| awesome.
| BerislavLopac wrote:
| I recommend trying https://icepanel.io/
| noxvilleza wrote:
| Recently been doing the same Structurizr consolidation since
| amongst our various teams we had a mish-mash of Lucidchart,
| Miro, and other collaborative design tools.
|
| One thing I was experimenting with (read: struggling with!) was
| a way to keep per-service (per-repo) architecture workspaces
| which are also synchronized on-commit to a central workspace
| and used !include to bind them together. The moving parts are
| not difficult - but writing your DSLs in a way that can handle
| this can be. This idea would let individual projects be self-
| sufficient and generate their own README doc diagrams as part
| of their own build process; but also have a central site which
| shows all the services as well as inter-service connectivity.
|
| Did you ever consider https://github.com/avisi-
| cloud/structurizr-site-generatr to bring together your ADRs in
| with your architecture, or do you keep them separate?
| jhund wrote:
| I looked at the avisi stucturizr-site-generatr, however,
| decided to render the docs via structurizr-lite. It provides
| better interactivity for C4 model diagrams, e.g., drilling
| down into diagrams and tooltips. I found the ADR integration
| in structurizr-lite sufficient.
| milesward wrote:
| No discussion of architecture diagrams is complete without the
| widest one ever: http://awsofa.cloud
|
| Thanks to Leo Z for keeping this online!
|
| [edited to fix link]
| paulddraper wrote:
| http://awsofa.cloud/
| turdprincess wrote:
| It's crazy to me that in todays remote first climate, many
| engineers still can't effectively make diagrams without an actual
| whiteboard and marker. A great way to stand out as a senior
| contributor is to get the hang of using a virtual diagramming
| tool, both for design documents and live discussions.
| samsquire wrote:
| I've had the idea that graph diagrams (including architecture
| diagrams) can be paged - you show a different set of
| links/vertices on each page of the same graph (show the same node
| but different enumeration of edges). Many codebase visualisations
| I've seen were too complicated to understand because the diagrams
| were so large. (I've seen some visualisations generated from code
| that were so small when panned around you have to zoom in. It's
| not a great experience.) I once wrote some tooling to generate
| Graphviz diagrams of RabbitMQ topic architectures based on log
| data by querying Elasticsearch to reverse engineer our
| architecture transitions between microservices, to see how the
| system actually worked in the present.
|
| My dream is that software architecture can have a late binding
| and can be transformed easily and trivially, without breaking any
| of its items it arranges.
|
| I am satisfied that I see the question "What is the main entry
| point?" in this post. This is so useful. I like the idea of an
| "entrypoint" folder for main(), routes and dependency injection
| containers.
|
| I think clear push/pull, async/synchronous, simultaneity and data
| flow can go a long way to understanding an architecture.
|
| I want software architecture to be a function of scaling
| requirements, that you can scale up and down.
| "architecture(scaling-requirements)"
|
| Wouldn't you love to be capable of changing the diagram to move
| code around? (You're in effect moving control flow or what I call
| the "tip of execution" by drawing lines or moving boxes around)
|
| I think your software architecture is a data structure, excepts
| it's really painful to change.
| alixanderwang wrote:
| D2 has keywords to split up diagrams into multiple pages:
| https://d2lang.com/tour/layers
|
| disclaimer: i work on it.
| mcbutterbunz wrote:
| > I've seen some visualisations generated from code that were
| so small when panned around you have to zoom in. It's not a
| great experience.
|
| I would love a Google-Maps-Like architecture diagram. Zoom out
| and you see high level flows, zoom in and you get the details
| you want to see. Different overlays to let you explore how
| systems are connected or how certain sub features work.
|
| Obviously this is hard to do and even harder to maintain but it
| could be really cool.
| [deleted]
| jtwaleson wrote:
| I'm working on exactly this idea, if it goes well I'll launch
| it as a product. I am trying to figure out the value
| proposition and who to sell it to and for how much. If anyone
| has ideas, please reach out. I would be very grateful.
| algomammoth wrote:
| I am also working the on a personal project like this in my
| free time, but would really like to see others' work or
| even contribute to them. Would you be up for exchanging
| ideas?
| JanitorBrian wrote:
| Sounds like http://icepanel.io/
| Veuxdo wrote:
| > I've had the idea that graph diagrams (including architecture
| diagrams) can be paged - you show a different set of
| links/vertices on each page of the same graph (show the same
| node but different enumeration of edges)
|
| You're describing something very similar to Ilograph[0] with
| its multiple perspectives.
|
| [0] https://app.ilograph.com/demo.ilograph.Ilograph/Request
| oaiey wrote:
| The diagram industry is ready to be disrupted. Views on views,
| your pushing idea, etc. So many ideas.
|
| Right now most tools including lucidchart and old timers like
| Enterprise architect are far too static
| moribvndvs wrote:
| I introduced C4 into my org a few years ago after disparate and
| unfocused documentation (if there even was any) and a lack of
| organizational competency on our own systems.
|
| We've found that you get a lot of value out of the first two
| levels of C4 alone. If your shop is good at UML and keeping it
| up-to-date, awesome, that work snaps right in as the additional
| layers. But whether you do 3 and 4 or not, context and container
| give everyone a lay of the land in easy to digest, progressive
| glimpses. Plus, the approach is so simple you can use it in
| whiteboard sketches, back of the napkin, or whatever you've got.
|
| Personally, I use PlantUML with a plug-in for your IDE of choice
| to author our formal artifacts. Excalidraw for doing it during
| real-time collaboration sessions. All of this is free.
| MrJohz wrote:
| I found my big problem with C4 was that it was too rigid to get
| the architecture quite right, so I ended up either with a
| diagram that felt overall too low-level (because I'd had to
| drop down a level to get the relevant details in), or a diagram
| that was too high level (where I'd just skipped the bits that
| were with discussion, and now needed to add more written
| documentation to make up for it).
|
| I really like diagramming, and I tend to do it whenever
| architecture comes up, but the best tools I've found are just
| pen and paper (or pen and whiteboard, or in a pinch Microsoft
| Paint). That way, you can draw exactly the relevant details for
| the discussion at hand.
|
| This doesn't work great for "diagrams as code", i.e. anything
| you want to check into git. I've recently had some success with
| ASCII drawings - there are a couple of online tools that draw
| the basics, and you can get the fine details by hand - but
| that's more time consuming, particularly for quick sketches.
| babblingfish wrote:
| Hi @kzhen, did you use a template for your website? Which
| template did you use?
| stetrain wrote:
| There's some discussion here about linking diagrams to code or
| vice-versa. And while that's useful for documenting code already
| written, where I personally have found diagrams to be the most
| useful is in the planning discussions before and during writing
| the code in the first place.
|
| A room full of people can talk about things for hours without
| making progress, but as soon as you starting moving boxes and
| arrows around on a screen suddenly people have more targeted
| thoughts about what they agree with or what should change.
|
| The diagram is useful for planning the extend and structure of
| the work to be done, and coordinating the team that is building
| it to make sure we have a shared mental model.
|
| Once that project is done, the diagram is likely already out of
| date. No plan survives contact with the enemy and all that. But
| for this use case its job is complete and it can be discarded or
| archived with the rest of the planning work.
|
| Diagramming for long term documentation is a slightly different
| use case, and for that I tend to agree more with documentation
| that at least lives with the code and can be updated alongside
| it, manually or automatically. I just personally haven't worked
| in orgs large enough to pay off that level of investment.
| jacurtis wrote:
| Yes, yes, a thousand times yes!
|
| I have been trying to enforce this concept inside of my current
| organization. There is the saying that a picture is worth 1,000
| words. I would extend that, suggesting that a diagram is worth
| well over 10,000 words.
|
| As an example, we had a project at work that kept getting
| thrown on my desk and every time it showed back up I would
| respond back with 20 questions based on limited writeups and
| JIRA tickets. Each time it would come back, I would get more
| confused, my team got confused, the architect was confused.
| Everyone was on different pages.
|
| Then finally, we brought a new technical project manager onto
| the project (at my bequest to the CTO) and within a week that
| TPM created a diagram, we have one 30-min meeting where he
| presented the diagram. We then realized that each team was on
| completely different pages with what needed to be built.
| Everyone asked a few questions, but there were far fewer
| questions than earlier because many of the questions were
| answered by the diagram. We then built out the solution 3 weeks
| later.
|
| So we spent 10 weeks spinning our wheels, building, unbuilding,
| rebuilding, and being confused as we all tried to get in
| alignment. THen one diagram and a 30 minute meeting later and
| we all left understanding exactly what we needed to do, we were
| all in alignment on the project and we were confident in what
| we needed. It also helped us call out things gaps in the
| initial solution, which we probably never would have identified
| until we ran into the problems when following the earlier
| method.
|
| One diagram can save HOURS (even tens of hours) of time for
| everybody. It reduces errors and misconfiguration and aligns
| teams. Diagrams are your best friend. No matter how simple
| something is, I always make a diagram.
| llanowarelves wrote:
| They are great because you can find so many problems at much
| lower cost earlier. And communication across domain and skill
| levels.
|
| Maybe their unpopularity among developers stems from trauma of
| the UML+OOO+Waterfall days and an overcorrection in the
| opposite direction.
|
| Or many more are doing it and just not talking about it since
| it's not as exciting as code.
| buro9 wrote:
| https://c4model.com/img/c4-overview.png
|
| That's what the argument is... and I'm in favour, there used to
| be such great architectural tools that were mostly UML but they
| did this well.
|
| I miss Visio, it was awful but everyone used it and it improved
| communication.
|
| I feel Google Suite is missing an equivalent, it's now draw.io,
| there's a real gap here.
| oaiey wrote:
| UML is awful when you pick up its meta stuff and try to use it
| 100% perfect.
|
| Otherwise it has all critical modeling methods and established
| a shared visual understanding. I prefer UML any day over eg
| lucidchart or Visio. Not that they cannot draw an architecture
| but boxes are what exactly again there?
|
| I especially like UML because there are no AWS logos and
| database icons. When drawing diagrams I am not there to impress
| how many icons I can do.
| dragonwriter wrote:
| > I miss Visio, it was awful but everyone used it and it
| improved communication.
|
| Did it go somewhere?
|
| (I generally prefer more declarative diagramming now --
| mermaidjs is my go to -- but Visio is still around and widely
| used.)
| hbcondo714 wrote:
| There is still no desktop version of Visio for macOS
|
| https://support.microsoft.com/en-us/office/use-visio-on-a-
| ma...
| cwdegidio wrote:
| When I need to create diagrams for anything (systems, code
| architecture, component design, etc) I reach for
| OmniGraffle on macOS. I've tried to use other tools, but it
| has served me well for years.
| buro9 wrote:
| > Did it go somewhere?
|
| Lost it's ubiquity.
|
| There was a period in which you could rely on almost everyone
| to have it, which made it an attractive, convenient and low
| friction way to share diagrams that people could edit and
| update.
| DenisM wrote:
| Have you tried Lucid Charts?
| tetha wrote:
| Mh. I'm not dealing in software architecture and much rather
| infrastructure architecture. But it's great to see that the
| onboarding documentation I'm currently writing Is mirroring the
| C4-architecture to a decent degree.
|
| Like, at the highest level, we have the different nomad clusters
| with stuff around them, and how these are used at a business
| level, relevant regulations and such. This splits into a number
| of identically structured datacenters with a number of
| connections between them. Then, each datacenter consists of a
| number of software clusters, some deployed, some not deployed.
| It's pretty much the same code with the same toggles, just
| somewhat different due to different underlying cloud providers.
| What clusters are deployed or not deployed is a risk-management-
| decision, as well as a business decision. But that's when the
| highlevel overviews stop, because then you get into the weeds.
| And not just a little bit, that's when you need chops to manage
| postgres to manage some of those clusters.
|
| But I'm putting a lot of hope into these diagrams and
| explanations for onboarding new colleagues, or maybe presenting
| the infrastructual ideas at meetups or conferences. Nothing
| against them, but a lack of an abstract understanding of a few
| high level ideas is really hurting a few new colleagues.
|
| Like, if I have a ticket, what set of systems would be right to
| work with? What happens if the ticket specifies ... other
| systems? What if you follow a runbook and the runbook suddenly
| banks portside really hard and tells you to touch systems outside
| the cluster you're working upon? In most cases, this is going to
| be wrong. It might be hard to determine what would be correct
| here, but with a decent grasp, it usually ends up easy to
| determine if the path isn't correct.
| quickthrower2 wrote:
| Good cookie banner system. Basically text at the point of needing
| a cookie instead of a popup regardless.
| jrimbault wrote:
| I failed a number of technical interviews because I can't make
| architecture diagrams.
|
| I come out of the first tech interview, coding/debugging, with
| praises. But then comes the second, the architecture interview,
| and I can't for the life of me draw the architecture of anything.
|
| I don't know how people learn to do that, I've learned to
| code/debug by being obsessive about it. But I don't see how that
| happens for system architecture.
|
| I've never used diagrams in my day-to-day work, so when it comes
| up in interviews I'm always surprised.
| sarchertech wrote:
| Do you know how to design systems, and you just can't draw
| them? Or do you need to learn how to design systems.
|
| If it's the former, just practice drawing something you've
| designed with boxes, labels, and arrows.
|
| I'd it's the latter I'd recommend
| https://www.goodreads.com/en/book/show/54109255 as a good intro
| to the kind of "systems design" they do in interviews.
| kzhen wrote:
| Hi jrimbault, article author here, like any skill this needs
| to be developed. As sarchertech says if you already know how
| to design systems but struggle with the drawing then practice
| is the key. When I started out the diagrams I produced were
| messy and not very presentable, but I kept refining them.
| Take the opportunities you have before you, for example, if
| you're building a system at work then take some time to try
| and draw up some architecture diagrams and run them by some
| people who you think will give you good feedback. Then keep
| refining them. If it's the later then there are some videos
| on youtube that introduce the C4 model - the key thing is to
| pick a method and try to stick with it, whether that is c4 or
| arch42 etc, try to learn the underlying principles and apply
| them.
| jroseattle wrote:
| You're going to get a lot of advice, but some general comments
| for your consideration. As always, your mileage may vary.
|
| > failed a number of technical interviews because I can't make
| architecture diagrams
|
| I would caution against correlating interview failure to a lack
| of diagramming skill. Diagramming is a teachable skill; how to
| formulate architecture is much more complicated. If I am
| considering hiring someone who I see can design strong
| architectures but couldn't represent that in a diagram, I'm
| probably not dismissing them because of their drawing skills.
| But that's only when I believe they can design an intended
| architecture.
|
| > I can't for the life of me draw the architecture of anything
|
| I had an engineer on one of my teams who had the same problem.
| With him, he understood some things but in other aspects he was
| more murky. So, I asked him to start by writing down the
| architecture. Literally, write words and sentences that
| describe the collective of systems, i.e. Service "A" is a REST
| API, and it connects to Database "B"; a client connects to
| Service "A" over HTTPS, etc. etc. I don't know if this would
| help, but if you can do that, you can start to translate the
| words to pictures.
|
| > I don't know how people learn to do that
|
| By doing. I don't know anyone who has ever been trained to
| create an architecture diagram that knew what they were talking
| about. Just start small, and then ask someone to describe it
| back to you. When you begin to hear what you consider to be
| correct, you'll know you're making progress.
|
| > I've never used diagrams in my day-to-day work
|
| This tells me a couple of potential things: you're possibly not
| working in complex or large systems, or maybe are not
| responsible for communicating those systems to others.
| "Complex" is a relative term, so interpret that as you may.
| Ultimately, arch diagrams serve as a way to visualize
| complexity with the goal of letting others understand.
| politician wrote:
| The ask is to flatten a multidimensional space into a 2D plane,
| so out of the gate you're going to have problems. A really good
| architectural diagram doesn't have a lot of crossed lines, but
| you can only really do that when you have a small number of
| nodes or when the dataflow is broadly unidirectional.
|
| The interview is inherently unfair - when you use a drawing
| tool to build diagrams the work is iterative, but erasing
| marker during an interview looks like you've made a mistake.
|
| Start with a small top-level diagram, then build a hierarchy of
| increasingly detailed diagrams. Use the opportunity to steer
| the interviewer ("which area would you like to see in more
| detail?"). It also helps to have an understanding of how small
| bits of code map to graphical sketches, so that you can compose
| them later.
|
| Also, keep in mind that issues like poor handwriting and sloppy
| lines are exacerbated by large detailed diagrams.
| swozey wrote:
| I work in platarch and I'll fully admit that my diagrams aren't
| the best, pretty ugly tbh. The people who do great diagrams
| typically have a lot of experience drawing them on whiteboards
| during meetings. It just hasn't been something I've done much
| and do it even less now that WFH. If you want to improve I'd
| recommend getting a whiteboard for your office and just start
| using it, then also learn mermaid or whatever language/app you
| want to use.
|
| I did use to make diagrams all the time when I was a field
| engineer for a distro company. Getting one of those small wacom
| tablets is really helpful in that case. I could draw in
| whatever app I was using at the time like draw.io or diagramly,
| I forget.
|
| I guess if we're all WFH now the latter is more important.. not
| sure if I'll ever have to whiteboard again..
|
| Also, I ran across this today, making diagrams as gifs. Really
| interesting. Way too much work for me, though -
| https://aws.plainenglish.io/aws-architecture-in-motion-creat...
| OJFord wrote:
| Use the tools you know and all that, but PowerPoint seems
| like a roundabout/hard way of doing that to me - I'd just
| make the base in whatever diagramming tool I'm using, then
| add the colour/dot/whatever variation for each frame (cf.
| PowerPoint slide), rendering/saving each image, and then look
| up the args for `mogrify` to combine them into a single
| animated gif. Or there's probably a dozen SEO'd ad-chucking
| websites that'll do it too if you prefer (& it's not
| sensitive).
| swozey wrote:
| I wonder if theres some image openAI thing I can run a
| diagram through to add it lol. Theres not a chance I'm
| spending that long unless it's maybe for an interview.
| tough wrote:
| In fact ChatGPT does have diagraminig plugins you can
| talk to and output valid code-based diagrams.
|
| Havent tried.
| swozey wrote:
| I totally missed that. I enabled plugins awhile back but
| didn't know how to use them, you have to use gpt4 and
| click an arrow at the top. There's an AWS arch diagram
| plugin.
|
| Anyway, I tried to get it to diagram a multiaz
| multiregion AWS nodejs frontend w/ rds backend app and it
| kept hitting api limits. I hate that that's a problem
| when I'm paying $20/mo but whatever. Like, just SLOW down
| the api calls. Stop ending the entire response. It's
| frustrating. Then it just tries again and hits the same
| limit. Some AI.
|
| I then shrunk it to something tiny just to see what it
| was, because I have no idea if its a mermaid diagram or
| uses the AWS icons or what, and it send me a broken image
| link. I told it the image didn't show up, and it sent me
| a direct S3 link. The S3 link gave me access denied. lol.
| icedchai wrote:
| There is some "art" to it, but if you can draw boxes, arrows,
| and labels, you can make architecture diagrams. Basically,
| organize the boxes in layers and connect with arrows to
| represent request/response flows. You need to put in enough
| detail to make the diagram useful (or at least seem that
| way...), but leave a bunch out, otherwise it's too noisy. If
| you have too many arrows intersecting, you should rearrange
| things.
| hitchstory wrote:
| Architecture diagrams are great and do indeed enable better
| conversations. They are just expensive to build, expensive to
| maintain and go out of date fast enough that they're practically
| ephemeral.
| Veuxdo wrote:
| > They are just expensive to build, expensive to maintain and
| go out of date fast enough that they're practically ephemeral.
|
| I agree with this if you're using drag-and-drop diagramming
| tools. Diagrams-as-code is a potential solution IMO:
| https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
| steve_adams_86 wrote:
| I'm a fan of systems where the diagram and code can be
| changed on both sides, too. Though they lack flexibility and
| require a sort of convention or framework to bind both sides.
| Often they can work incredibly well but tend to have a narrow
| use case.
|
| Something like XState and the Stately studio editor comes to
| mind; it'll generate state machine diagrams from code or vice
| versa. But it only manages state charts. I'm not sure how you
| could create something similar with more broad applications.
| Though, maybe that's not necessary or necessarily a good idea
| anyways.
| kandros wrote:
| I've used old xstate visualizer (like 4 years ago) as a
| communication tool to review flows with domain experts
| before implementing something, made conversation and
| spotting problems so easy
| pnathan wrote:
| Also, in order for them to capture appropriate granularities of
| detail, they take a lot of time and conversation with readers.
|
| I usually go with as little graphs as possible and prefer to
| write text; it can capture more, better, faster, and be more
| iterable. For specific areas like state machines or packet
| sequences I will drill into graphical representations more but
| otherwise... eh. Text wins.
| gardenhedge wrote:
| The real key for diagramming is representing your system from
| different views - this is what c4 promotes. But I don't believe
| you need strictness - use whatever diagramming tool you want,
| include whatever layers are useful to you and your team, etc.
| jedberg wrote:
| An article about architecture diagrams without a single example?
| kens wrote:
| You probably want https://c4model.com/ which explains what a C4
| architecture diagram is. (See the first footnote in the
| article.)
| Yeroc wrote:
| Relevant quote from the article:
|
| "The lack of real-world examples available - this obviously
| isn't a limitation of the model itself but rather due to the
| fact that companies don't want to advertise their architecture
| in detail in public."
| jedberg wrote:
| Sure, but if you're going to extol the virtues of
| architecture diagrams, it would help to either find _one_
| good one or make one up.
| numbsafari wrote:
| These are great. You can include them in GitHub-flavored markdown
| files and they work.
|
| For a long time they were pretty broken, but they are looking
| much better supported now.
|
| https://mermaid.js.org/syntax/c4.html
|
| https://github.blog/2022-02-14-include-diagrams-markdown-fil...
| politician wrote:
| One of the areas I would like to see addressed in guidance for
| drafting both architecture diagrams and specifications is in the
| documentation of the basis for design decisions. Which risks
| catalyzed a particular design or approach on a particular feature
| and to what degree?
|
| In my own work, when I need to revisit a spec months afterwards,
| I often have trouble because I've forgotten parts of the context
| that I had at the time the spec was drafted. The situation is a
| bit like the Chesterton's Fence where the original person that
| set the fence in the middle of the road has also partially
| forgotten why it needs to be there. It was so obvious at the
| time...
|
| Do others supplement their architecture diagrams and
| specifications with a cross-refenced list of risks, alternatives,
| and probabilities?
| kzhen wrote:
| Hi, article author here, we supplement our architecture
| diagrams with Architectural Decision Records (ADRs)
| https://github.com/joelparkerhenderson/architecture-decision...
| in the ADR we capture: - options considered - pros/cons of
| different options - chosen option - who was involved in making
| the decision
|
| there are a few other fields like component, product etc these
| are very useful for capturing decisions and something I should
| have mentioned in the article.
| nextworddev wrote:
| What are your favorite diagram tools? Looking for excalidraw
| alternatives with good Cloud resource icon support
| stetrain wrote:
| At the moment I have been trying out FigJam, mostly because in
| an org that already uses Figma it's convenient and doesn't
| require another signup, account, or subscription.
|
| It's not particularly targeted at software diagrams, but when
| diagramming for and during planning and design meetings I
| prioritize quick buildout and editing over conforming to any
| particular standards or iconography.
| DenisM wrote:
| Lucid Charts
| artur_makly wrote:
| https://VisualFlows.io it is 100% free - and we offer all AWS,
| GCP, and Azure icons, or just add your own via drag n drop.
|
| Sample UML:
| https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
| oaiey wrote:
| The "Sample UML" is no UML. My apologies for being rude but
| this is not a component diagram nor any other standardized
| UML diagram. UML components have a visual indicator (to not
| confuse them with classes), use ports and connectors are
| consistently applied and do not vary just because the node is
| a S3 bucket or whatever.
|
| It is a valid diagram helping understanding something and the
| tool seems awesome but please do not pitch this as "Sample
| UML"
| vidoc wrote:
| The only 2 techs I use for stuff like that are
|
| Asciiflow https://asciiflow.com/#/ Dot https://graphviz.org/
| avs733 wrote:
| In my prior experience (inside and outside of software, anything
| having to do with a process) I think there is another situation
| where diagrams are enablers that they missed. Finding consensus
| on how the thing currently works.
|
| When these issues are takled about in words, through code,
| through hand waving whatever - I have experienced that the
| details often mask ensuring that everyone is on the same basic
| page. Often when there has been confusion it has taken someone
| pulling the group back and noting that 'Bob things A is connected
| to B and then connected to D but Alice thinks A connects to C
| before connecting to D"
|
| Just putting a architecture diagram of a process up helps find
| shared understanding.
| jimmychoozyx wrote:
| TLDR: Water is wet. Sky is blue. Grass is green.
| kannanvijayan wrote:
| I find architecture diagrams particularly useful for interviews
| of high-level candidates. I'll structure the first half as an
| informal conversation where I pick up some technical work they've
| done and get them to talk about it in depth.
|
| The second half is usually explaining the 10kft and 1kft
| arhitectural overview of our product. However, I find that pre-
| prepared architecture diagrams are not that helpful in this case.
| I just open up an excalidraw tab, screen share, and sketch out
| the diagram in real-time, explaining things as I go along, and
| trying to elicit conversation about the design.
|
| I do this because my biggest challenge when tackling new work is
| not necessarily the code, but the context of it. Where does this
| live? Where does it receive its inputs from? Where dose its
| outputs go? How are all of these things organized into the bigger
| picture? What gets persisted? What's transient?
|
| A good grasp of overall architecture allows you to produce your
| own heuristic for how to navigate the code, where to look for
| problems, build internal models of where things might be going
| wrong, etc.
|
| The sketches get thrown away each time. The process of drawing it
| out and explaining it is the value.
| ShadowBanThis01 wrote:
| Your approach sounds like what I'd expect for an experienced
| hire. Good for you.
|
| Sadly, it's not what I've experienced lately.
| glonq wrote:
| I documented the architecture of my previous project using C4. It
| worked well, especially because they had templates available for
| draw.io which is my preferred tool for diagrams.
|
| And I agree that having way more C4 examples of real-world
| projects would be very useful!
| frozenport wrote:
| too long didn't read, no diagrams
| abra0 wrote:
| What are the tools people use to draw diagrams? I've tried many
| things and settled on Miro on an iPad (infinite canvas + pencil),
| but I still think this space is underinvested in.
|
| The downside of diagrams from code is the loss of the wysiwyg
| aspect -- I want to be able to manipulate things visually.
| tru1ock wrote:
| I have been using https://www.yworks.com/products/yed for
| years. You can import a c4 palette probably. I do not really
| stick to specific shapes but use what makes sense for the
| context.
| artur_makly wrote:
| https://VisualFlows.io
|
| sample architecture:
| https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
| afarrell wrote:
| Cell phone camera on a little holder pointed at a piece of
| paper. Then I join as a second participant, mute it, and turn
| the volume off.
|
| Or ipad and apple pencil on google docs jamboard using Duet to
| sketch things out.
| foobarian wrote:
| I like Gliffy built into Confluence because it's default at
| work. I also like excalidraw and was hoping to test the
| collaborative feature for video calls. I think the ephemeral
| nature of the diagrams is just fine, it's essentially a
| whiteboard with some QoL features like persistence, pre-
| population, and undo/redo.
| Supermancho wrote:
| miro works slightly better than Gliffy, imo.
| p10r wrote:
| Http4k, a http library for Kotlin, has an, in my opinion, great
| way of generating documentation for you [0]. They explain it in
| more detail in their talk [1] and also have an example repository
| [2], if you favor to look at code.
|
| [0]
| https://www.http4k.org/blog/http4k_v5/#tracerbullet_a_brand_...
|
| [1] https://www.youtube.com/watch?v=CrslqbMbaD8
|
| [2] https://github.com/http4k/exploring-the-testing-hyperpyramid
| [deleted]
| vaughan wrote:
| Code should generate diagrams automatically as you write it. Then
| you can see the complexity increase as you go, instead of looking
| back on a tangled mess.
| SkyPuncher wrote:
| How do you do that with disparate, disconnected systems?
| vaughan wrote:
| Parse all the code with tree-sitter[1].
|
| [1]: https://tree-sitter.github.io/tree-sitter/
| commandlinefan wrote:
| I've worked with documentation auto-generators before, and the
| problem they have is that they can't figure out which
| references are relevant and which aren't. I remember auto-
| generating a class diagram of a Java project in the late 90's
| and it showed every class having a reference to the class
| "java.lang.String". Generators have gotten (a little) smarter
| with one-off heuristics like "treat the class String as if it
| were a primitive", but they're still way more cluttered than a
| knowledgeable human would ever come up with.
| Supermancho wrote:
| > Code should generate diagrams automatically as you write it.
|
| That's fine for some purposes, but for general discussions
| around many subjects (project planning, security, integration
| testing, etc) you won't get there from generated diagrams out
| of some code in an application.
| simonjgreen wrote:
| Is there something along the lines of C4 that is biased towards
| systems and infrastructure? Eg SaaS architecture, PaaS
| components, or pluggable architecture? (I suppose you could use
| the first 2 or 3 layers of C4)
| 123pie123 wrote:
| i always make diagrams even for very basic ideas - it helps you
| to explain and it also helps you to confirm your ideas
___________________________________________________________________
(page generated 2023-08-22 23:00 UTC)