this post was submitted on 21 Jun 2023
25 points (96.3% liked)
Experienced Devs
3954 readers
1 users here now
A community for discussion amongst professional software developers.
Posts should be relevant to those well into their careers.
For those looking to break into the industry, are hustling for their first job, or have just started their career and are looking for advice, check out:
- Logo base by Delapouite under CC BY 3.0 with modifications to add a gradient
founded 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
I've used it with a lot of success at my current and previous companies. To address a few of your cons:
Engineers are quickly comfortable with the tooling and VS Code plugins give you quick feedback. You can also point the plug in at a hosted instance to avoid running a local instance in Docker
Separation of different types of diagram is often a bonus—too often have I seen architects try to cover too many concepts in a single diagram—instead a Context diagram should define your system and its neighbours, a Container diagram the major pieces of your system, a Component diagram verges on design and is a good place for engineers and architects to converse. If a container or component has a particularly complex workflow, then a supplementary flow diagram helps. If it uses an extraordinary pattern, then a class diagram might help, and so on.
My main concern is this: We have a wiki, each component has some sort of a README. If we add C4 to the mix, then we will have technical documentation in 3 different places. I would love it if C4 would eliminate the need for a wiki. Then in a CI pipeline, we would fetch component READMEs from their repositories and merge all of them into a single C4. When a developer tries to understand a component, they would go to its diagram and view different aspects of it (some text, links to external API documentations, other sorts of diagrams, etc.).
I guess I need to start experimenting first to see if things work better than I expect. As you say, developers will not have huge problems once the workflow is in place.
I find keeping C4 diagrams in wikis often leads to them falling out of sync with the codebase. Ideally you'd keep the markup for the diagram in the relevant component repo and have a CI/CD process that keeps your diagrams up to date. I wrote a PlantUML Docker image for exactly that: https://github.com/robbell/plantuml-docker
Alternatively, Mermaid support is becoming more common—available in GitHub and Backstage TechDocs, and that allows you to embed diagrams in Markdown. Both PlantUML and Mermaid have support for linking to other diagrams I believe, and you could put your API definitions in your owning repos too using OpenAPI to keep everything together and in sync.