I'm diving into a new architecture project, and to be honest, I'm feeling quite overwhelmed by all the options available for diagramming. There are so many choices like C4, UML, sequence diagrams, and system maps. I'm really unsure where to kick things off! I'm also curious about how to determine the right level of detail to include without creating unnecessary documentation debt. I'm eager to learn about your workflows and strategies for keeping diagrams useful and manageable for the team.
6 Answers
If you’re lacking user stories, beginning with use case diagrams is a fantastic starting point. Software should solve real user problems, so understanding those problems is key. After establishing use cases, you can create high-level user flows if necessary. Then, once you understand the problem and requirements, an architecture and system diagram will follow naturally. I rarely go below that level unless something becomes unclear during development. Usually, code structure diagrams are automatically generated, as they're prone to change, unlike the core domain and architecture.
A solid approach is to pick one diagram for each specific problem you're facing. If a diagram doesn't address a real question or issue, it's probably not worth drawing. That guideline can really help you minimize the clutter!
That's a great point! How do you keep your team aligned on what needs to be diagrammed?
From my experience, use diagrams primarily for decision-making rather than completeness. I usually start with a high-level system view, and then create diagrams only when a decision is stuck. For instance, I only use sequence diagrams when asynchronous flows get tricky. I also find Miro handy for quick sketches during discussions—it’s informal and intuitive, and it reduces the chances of getting bogged down with too much detail.
I like that perspective about clarity! How do you decide when a diagram is truly needed?
I don't really get why diagrams are so popular everywhere. They should only be made when there's a clear need.
I typically start with a super rough system map. If a diagram feels like homework rather than a tool for clarity, it’s probably too detailed. Diagrams should help to reduce meetings, not create new ones to explain them!
Absolutely, that's such a crucial point—diagrams should help streamline communication, not complicate it!
As someone with quite a bit of experience, I’d say that 95% of the time, you really only need a sequence diagram and a component diagram (like a system map). You need to illustrate the flow from the user to the system and back, as well as the relationships between your services and tech stack.
Keeping it to just those two diagrams sounds totally doable!
Honestly, I used to have a different view, but these days I just go with Mermaid. You can pick your renderer and modify the output to your liking. Plus, with LLMs getting better, you can simply tell it to link services or rename items, and it takes care of the rest since it's all text-based!
LLMs are definitely advancing! But sometimes it feels a bit scary how replaceable we might seem.
Yeah, LLMs also do a fantastic job creating diagrams in SVG, which is great for presenting to stakeholders and more flexible for complex structures.
That makes complete sense! Focusing on the problem and domain first seems like a logical approach, and architecture diagrams can evolve from there.