Love the post and the checklists. I especially like that you focused on how to review architecture diagrams. Only through peer feedback and iteration can we really make these diagrams useful for our teams!
One thing immediately jumped out about your improved version of the diagram: it's much harder to read! This seems like a small thing, but the original diagram could be glanced at and comprehended. In particular, in the new diagram:
The text is too small.
There are sentences and phrases where there should be words, etc.
Your improvements certainly stand up to closer scrutiny and rewards study, but at the cost of high-level legibility and immediacy.
I realize that may be more of a complaint about Structurizr, but I think the granularity of information packed into these diagrams is also a helpful thought exercise - how detailed should this diagram be?
Author "Software Architecture for Developers" | Creator of the "C4 model for visualising software architecture" | Founder at Structurizr | Software architecture training at architectis.je
Thanks, glad you found the post useful! I prefer having the detail, because it helps prevent many questions. I'd definitely recommend keeping the text short though - a single sentence, or perhaps 5+/-2 bullet points. I also encourage "more text" on hand-drawn diagrams too. Here's an example from a workshop.
If you're wondering why I encourage the descriptive text, here's a link to the section in one of my talks where I discuss this. I do appreciate that sometimes you might want to hide the descriptive text (e.g. for presentations), so Structurizr actually allows you to turn that off with a single keyboard shortcut.
It's nice to have options!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Love the post and the checklists. I especially like that you focused on how to review architecture diagrams. Only through peer feedback and iteration can we really make these diagrams useful for our teams!
One thing immediately jumped out about your improved version of the diagram: it's much harder to read! This seems like a small thing, but the original diagram could be glanced at and comprehended. In particular, in the new diagram:
Your improvements certainly stand up to closer scrutiny and rewards study, but at the cost of high-level legibility and immediacy.
I realize that may be more of a complaint about Structurizr, but I think the granularity of information packed into these diagrams is also a helpful thought exercise - how detailed should this diagram be?
Thanks for the post! 🍻
Thanks, glad you found the post useful! I prefer having the detail, because it helps prevent many questions. I'd definitely recommend keeping the text short though - a single sentence, or perhaps 5+/-2 bullet points. I also encourage "more text" on hand-drawn diagrams too. Here's an example from a workshop.
If you're wondering why I encourage the descriptive text, here's a link to the section in one of my talks where I discuss this. I do appreciate that sometimes you might want to hide the descriptive text (e.g. for presentations), so Structurizr actually allows you to turn that off with a single keyboard shortcut.
It's nice to have options!