101–110 of 141 posts
(article with no diagrams)
I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/ . It's very easy to embed a C4 diagram into a markdown document. The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (fo…
Recently been doing the same Structurizr consolidation since amongst our various teams we had a mish-mash of Lucidchart, Miro, and other collaborative design tools. One thing I was experimenting with (read: struggling with!) was a way to keep per-service (per-repo) architecture workspaces which are also synchronized on-commit to a central workspace and used !include to bind them together. The moving parts are not dif…
But C4 seems almost too lightweight to merit a name. Its drawing toolbox is just boxes, arrows, stick figures and datastore, with 'boxes' meaning one of four different things depending on the diagram level (Context, container, component, code). But the boxes are the easy part! The only thing I want a diagramming standard to settle on is 'what do the arrows mean, and which direction do they go in', and C4 fails on that front - the arrows mean 'whatever you label them to mean' - they are literally just 'relationships', so on one C4 diagram you might have one arrow that means 'writes data to' and another one that means 'is written to by', and that's fine.
The C4 docs say little of relationships, apart from, 'Try to be as specific as possible with the label, ideally avoiding single words like, "Uses".'
The C4 examples contain lots of relationships labelled as 'Uses'.
So I'm sorry, but I just don't see the value C4 brings to the table. Do I need to pay for the training?
What are the tools people use to draw diagrams? I've tried many things and settled on Miro on an iPad (infinite canvas + pencil), but I still think this space is underinvested in. The downside of diagrams from code is the loss of the wysiwyg aspect -- I want to be able to manipulate things visually.
Cell phone camera on a little holder pointed at a piece of paper. Then I join as a second participant, mute it, and turn the volume off. Or ipad and apple pencil on google docs jamboard using Duet to sketch things out.
I did something similar, but used OBS. There are a few ways to feed video from a cell phone into it. Gives you the chance to do any zooming/cropping/etc to account for limitations in where you can place the phone. As well as adjust brightness/contrast/white balance if you’re really anal about that kind of stuff.
From there I open the feed in a “projector” window and screen share that.
As someone with aphantasia, they don't help me memorize relationships, so to get them into my working memory, I have to translate a diagram into bullet points: it's so much easier just to start with those bullet points of what components we've got, what they consist of and what relationships they have (you know, just like code itself).
And having done theoretical (read: abstract) maths too, that's good enough for me to work with complex and intricate relationships.
I still understand that it's not like that for most everybody else, but for some minority of us, they are just a bad way to write text/thoughts out as the graphical layout has no benefits. Yes, you do learn to read and create them, but it's an extra effort that you do for others' benefit.
I've had the idea that graph diagrams (including architecture diagrams) can be paged - you show a different set of links/vertices on each page of the same graph (show the same node but different enumeration of edges). Many codebase visualisations I've seen were too complicated to understand because the diagrams were so large. (I've seen some visualisations generated from code that were so small when panned around you…
D2 has keywords to split up diagrams into multiple pages: https://d2lang.com/tour/layers disclaimer: i work on it.
Now if I could only get Posit to put D2 into Quarto alongside Mermaid and GraphViz, I would be set.
I introduced C4 into my org a few years ago after disparate and unfocused documentation (if there even was any) and a lack of organizational competency on our own systems. We’ve found that you get a lot of value out of the first two levels of C4 alone. If your shop is good at UML and keeping it up-to-date, awesome, that work snaps right in as the additional layers. But whether you do 3 and 4 or not, context and conta…
I found my big problem with C4 was that it was too rigid to get the architecture quite right, so I ended up either with a diagram that felt overall too low-level (because I'd had to drop down a level to get the relevant details in), or a diagram that was too high level (where I'd just skipped the bits that were with discussion, and now needed to add more written documentation to make up for it). I really like diagram…
I introduced C4 into my org a few years ago after disparate and unfocused documentation (if there even was any) and a lack of organizational competency on our own systems. We’ve found that you get a lot of value out of the first two levels of C4 alone. If your shop is good at UML and keeping it up-to-date, awesome, that work snaps right in as the additional layers. But whether you do 3 and 4 or not, context and conta…
I found my big problem with C4 was that it was too rigid to get the architecture quite right, so I ended up either with a diagram that felt overall too low-level (because I'd had to drop down a level to get the relevant details in), or a diagram that was too high level (where I'd just skipped the bits that were with discussion, and now needed to add more written documentation to make up for it). I really like diagram…
If you have smaller or less complicated systems, or your audience is smaller or all peers, then I could also see C4 as having fewer benefits.
Code should generate diagrams automatically as you write it. Then you can see the complexity increase as you go, instead of looking back on a tangled mess.
I've worked with documentation auto-generators before, and the problem they have is that they can't figure out which references are relevant and which aren't. I remember auto-generating a class diagram of a Java project in the late 90's and it showed every class having a reference to the class "java.lang.String". Generators have gotten (a little) smarter with one-off heuristics like "treat the class String as if it w…