5 ms·

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 o

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 container give everyone a lay of the land in easy to digest, progressive glimpses. Plus, the approach is so simple you can use it in whiteboard sketches, back of the napkin, or whatever you’ve got. Personally, I use PlantUML with a plug-in for your IDE of choice to author our formal artifacts. Excalidraw for doing it during real-time collaboration sessions. All of this is free.

MrJohz 3y ago
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 diagramming, and I tend to do it whenever architecture comes up, but the best tools I've found are just pen and paper (or pen and whiteboard, or in a pinch Microsoft Paint). That way, you can draw exactly the relevant details for the discussion at hand. This doesn't work great for "diagrams as code", i.e. anything you want to check into git. I've recently had some success with ASCII drawings - there are a couple of online tools that draw the basics, and you can get the fine details by hand - but that's more time consuming, particularly for quick sketches.
- Onawa 3y ago
  I had the same issue as you with C4, and d2 was the perfect balance of simple enough for creating diagrams almost at thinking speed, but with enough features (and growing) that I have been very pleased with it.
- moribvndvs 3y ago
  I can see having to swap back and forth between levels to pull up technical specifics as mildly annoying. I guess I’ve gotten used to it, either way having a source of truth that multiple roles can consume has been worth it in my org. 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.

MrJohz 3y ago

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 diagramming, and I tend to do it whenever architecture comes up, but the best tools I've found are just pen and paper (or pen and whiteboard, or in a pinch Microsoft Paint). That way, you can draw exactly the relevant details for the discussion at hand. This doesn't work great for "diagrams as code", i.e. anything you want to check into git. I've recently had some success with ASCII drawings - there are a couple of online tools that draw the basics, and you can get the fine details by hand - but that's more time consuming, particularly for quick sketches.

Onawa 3y ago
I had the same issue as you with C4, and d2 was the perfect balance of simple enough for creating diagrams almost at thinking speed, but with enough features (and growing) that I have been very pleased with it.
moribvndvs 3y ago
I can see having to swap back and forth between levels to pull up technical specifics as mildly annoying. I guess I’ve gotten used to it, either way having a source of truth that multiple roles can consume has been worth it in my org. 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.