Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Architecture diagrams enable better conversations

unravelled.dev

Post reply on HN
Print view View original

21–30 of 141 posts

Re: Architecture diagrams enable better conversations

#21

Post by OJFord »

swozey wrote: post #14
jrimbault wrote: post #4

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…

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 that'll do it too if you prefer (& it's not sensitive).

Re: Architecture diagrams enable better conversations

#22

Post by taeric »

kzhen wrote: post #9
taeric wrote: post #2

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 n…

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 Produ…

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.

Re: Architecture diagrams enable better conversations

#23

Post by glonq »

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!

Re: Architecture diagrams enable better conversations

#24

Post by p10r »

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

Re: Architecture diagrams enable better conversations

#26

Post by Veuxdo »

hitchstory wrote: post #20

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.

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

Re: Architecture diagrams enable better conversations

#27

Post by gav »

taeric wrote: post #2

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

Re: Architecture diagrams enable better conversations

#28

Post by dragonwriter »

buro9 wrote: post #19

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.

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

Re: Architecture diagrams enable better conversations

#29

Post by DenisM »

buro9 wrote: post #19

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.

Have you tried Lucid Charts?
Post reply on HN