DEV Community


Discussion on: How to review a software architecture diagram

simonbrown profile image
Simon Brown Author • Edited

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!