| These DSL tools can be absolutely fantastic and feel powerful in the hands of one person, but the issues come when multiple people get involved. I train teams to use C4 diagrams, one of the most common issues they tell me they had in the past is the ivory-tower: someone somewhere created all the diagrams alone and dumps them on everyone hoping it will make the world better. The problem is that mode lacks the collaboration and mutual context-building to get everyone on the same page. Not everything needs to be a team effort, but a lot of your diagram work should shift towards a day-to-day tactical discussion (the deeper the C4 level the faster moving things will be). Shifting to a culture of shared context and the discipline of speaking the same language lets everyone have high clarity and move quickly. The problem with DSLs is they are often nudging people to work alone. Text editors like that are often not multi-player. You can get around it with a screen-share or even pair programming a diagram, but often the tools nudge behaviours of people into a mode where they just work alone and dump stuff out of the ivory tower. When I train teams who are coming in new to something like C4 I will use Miro specifically because they don't need any special DSL knowledge, and also especially because it is multi-player (everyone gets to draw and move stuff around). I find often people get a bit shy about touching the diagrams but in the training it is really important to get the whole team into the practice of seeing "oh yeah, this is a diagram I can touch too". For teams who've been through the basic training and gotten used to C4 diagrams to do specific jobs in their tech org, I move them into https://icepanel.io/ because the problems of that team have changed a lot. The initial problem was "I need to know how to structure a story and model my architecture at the same time". Once they got good at explaining their architecture they end up needing to model their architecture (a diagram is something different than a model) at a bigger scale (all those connections that make your diagrams too messy, the boxes that are important in context A but not context B, etc). I like IcePanel because I can slice out a "domain" of my model and show just that view of the world. For teams that have been trained to empower everyone to draw (instead of a single Benevolent Diagrammer For Life), having a multi-player system to manage the model and pick how to present a multi-dimensional subset of that better than just having a static DSL file or a Miro board (note: Miro is "fine" but it can quickly reach its limits). Basically, You get to keep the complexity of your model but only have a focused discussion on the relevant parts. Beyond that, there's a whole world of techniques on how to actually read an architecture diagram to spot problems, but that's just too much stuff to post in a comment here. The tl;dr is: Getting your teams to manage their architecture is multiple skills you need to build into the people on your team: collaborating, diagramming, modeling, analysis, and story-telling. I suggest starting in any tool where everyone can participate, and I don't think that's a DSL-based tool because of the UX. Those DSLs "nudge" your culture towards one where one person in the ivory tower drops an inaccurate and overly complicated one-size-fits-all diagram every 9 months and nobody knows with to do with it. It doesn't always happen, but it does increase the chances. Full disclosure: I'm the trainer mentioned in the article. Happy to answer questions here if anyone wants to debate or pick my brain. |