Really, the main struggle is tooling. So far, I am using PlantUML with a C4 model plugin. It's okay. I am thinking of switching to a visual diagramming tool, even though the author of the C4 model recommends against it, for some reason that I don't quite understand.
It seems this talk, which I'll have to watch later, is own the author's own tooling called Structurizr. While nice, the pricing is a bit strange. The on premise version is $50 minimum per month and is twice the cloud version. I feel like it's going to be hard enough selling the C4 model, and I don't think the pricing model works for something that will have a lot of work in the beginning and then become relatively static for mature products. I'd like to see a one-time purchase perpetual license.
For the diagrams as code solution, happily it looks like mermaid will soon support C4  so their should be native support in lots of places soon (github, gitlab and lots more have built in support for mermaid)
Not the speaker in the video, but the main reasons to not use drag-and-drop diagramming tools are summarized here: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
Yeah, you can argue that simple is better (I really loved https://www.simplediagrams.com/), but you still need _some_ ways to produce diagrams people will actually find pleasing. Diagrams to tell a story, with blocks that make sense in terms of looks, colors, and orientation. I want an open-source code-to-diagrams that can output as pretty diagrams as I make with LucidChart!
As for pricing, there's https://structurizr.com/help/lite, which is free, no?
Love seeing others exposed to it.
1. Internal maintenance; to understand the system's depths and how it came to be in its current state
2. External consumption; to see the pieces of the system, how they work together, and how to use them
In my research I stumbled across several viable documentation techniques/patterns that seemed to help us reach our doc goals. We decided to combine 3 of those techniques:
1. C4 Model (https://c4model.com/)
2. Architectural Decision Records (https://adr.github.io/)
3. arc42 (https://arc42.org/)
The result feels like more documentation than anyone will ever read, but it has allowed us to create a complete self-service set of documents that should allow our library to be used broadly across the org without our team becoming something like a tool support team.
While demonstrating or describing our system to people across the org (not just devs) we found that pointing to the top 2 levels of our C4 diagrams has been incredibly useful at helping describe the system and the work we're doing in the system. We've also received fantastic positive feedback from our audience regarding the diagrams and their ability to help clarify the concepts being described.
We decided to embed our diagrams directly into our markdown docs. The raw markdown looks like this:
## How It Works
A person uses the app, the app is compiled from the code, the code is maintained by developers.
Person(dev, "Developer", "A software developer")
Person(user, "User", "A person that uses the application")
System(app, "Application", "The application")
System(code, "Code", "Code repository")
Rel(dev, code, "Maintains", "Git")
Rel(code, app, "Produces", "Azure")
Rel(user, app, "Uses", "Web Browser")
This ends up being completely readable as a plain markdown file, but is enhanced by having a markdown preview tool like any of the major Git hosts (GitHub, ADO, etc.) because the PlantUML is hidden, but the diagram is presented graphically as a .png image. It also allows us to keep our documentation close to the code it represents, which has been a huge benefit in the organizing of documentation (vs adding another doc to the pile of outdated docs in our internal wiki).
That sounds too advanced although I could see an Sphinx doc plugin being able to do that, but not the more basic Markdown viewer in most hosts... so I'll guess that you meant to copy the embedded PlantUML lines to a temp file, and generate a .png, that gets stored together with the .md file.