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.
How do you do that with disparate, disconnected systems?
Architecture diagrams enable better conversations
41–50 of 141 posts
Re: Architecture diagrams enable better conversations
#42There'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.
Re: Architecture diagrams enable better conversations
#43I'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 n…
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 Co…
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.
Re: Architecture diagrams enable better conversations
#44What are your favorite diagram tools? Looking for excalidraw alternatives with good Cloud resource icon support
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.
Re: Architecture diagrams enable better conversations
#45I'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…
> 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 ha…
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.
Re: Architecture diagrams enable better conversations
#46Earlier quoted context omitted.
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 la…
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…
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.
Re: Architecture diagrams enable better conversations
#47https://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.
> 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.)
> 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.
Re: Architecture diagrams enable better conversations
#48An article about diagrams that doesn’t show a single one. Huh.
Re: Architecture diagrams enable better conversations
#49I'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…
D2 has keywords to split up diagrams into multiple pages: https://d2lang.com/tour/layers
disclaimer: i work on it.
Re: Architecture diagrams enable better conversations
#50I 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 cas…
Your approach sounds like what I’d expect for an experienced hire. Good for you.
Sadly, it’s not what I’ve experienced lately.