What does HackerNews think of C4-PlantUML?
C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures
That way in an editor like VS Code (e.g. where you have/make plugins to support) you can live preview the diagram in your editor while editing the related text - both get syntax highlighting etc. Using a tool like sphinx to tie everything together helps, as you can easily (enough) write extensions to handle quirks of your own setup reasonable if needed.
I've seen this work pretty well, in a /doc folder in the git repo with some autogenerated reference links as well, from the same repo. You either need the plantUML jar file local (and java, obv) or to point it at a rendering instance "local enough".
- https://github.com/plantuml-stdlib/C4-PlantUML - https://structurizr.com/ (by Simon Brown, the creator of the C4 model)
yes, if they're don't change frequently by non-technical people. There are tools allowing conversion between GDocs and markdown. So one can start with the GDoc at the initial non-tech collaboration stage, and once it's more or less stabilized, convert it to markdown and commit to a git repo.
> system design docs
yes - see C4-PlantUML[1]
> meeting notes
no, unless they're directly code related like ADRs [2,3].
Although, one can abuse Github Issues + comments for this, in my opinion it's better to use modern SaaS tools in this case, e.g. Loom, Descript, otter/gong, etc. - you can automate this process, e.g. transcribe the meeting's recording and add the issue/repo using Github Actions.
> etc.
To summarize: any piece of documentation/diagrams that has even minimal affinity to the source code and can be expressed in a text-based format.
I even store visual non-text based diagrams (non-manually editable XML) using Draw.io VSCode extension [4], or Miro board backups/dumps.
Use linters and automate with CI/CD (e.g. Github Actions).
Also I suggest to have a list of VSCode extensions for each text/diagramming format used in the repo. Maybe with the script to automate their installation.
--
[1] https://github.com/plantuml-stdlib/C4-PlantUML
[3] https://docs.aws.amazon.com/prescriptive-guidance/latest/arc...
[4] https://marketplace.visualstudio.com/items?itemName=hediet.v...
I could have never maintained the diagrams I used for other developers on my teams or folks on the audit/regulation side of thing without it.
The default styles are really unprofessional looking and I think a lot of folks look the other way once they see that. C4 diagraming with PlantUML is also a breeze for systems diagrams.
I'll throw in C4 Model [0] in here. It's a tool to visualize how system components connect at various level.
Unit tests, and code will help you understand the system bottom up. Documenting with C4 will give you an idea how the system is arranged top down. The context, component connections, etc.
I'm partial to C4-PlantUML [1] because you can diagram your system using code; you can version it. You don't have to worry about the layout. It gets out of your way.
[0]: https://c4model.com/
As others have mentioned, to effectively communicate a system you must limit the context to particular layers of abstraction, and C4 is a good approach to doing just that. There's also a C4 plugin for PlantUML[1].
But don't forget that, as with all visualizations, audience and purpose are key.
Consider whether you are addressing short-term needs (eg identifying inefficiencies, modeling for a client pitch) or long-term needs (eg knowledge retention, managing complexity). If your audience's needs are short-term, you can certainly get by with much simpler tools (eg Inkscape, excalidraw/draw.io/etc, picture of a whiteboard, doodles on a napkin).
Also consider whether or not you actually have a problem better served by bottom-up (ie generated) visualizations (eg ERDs for database schema refactoring, heatmaps for profiling, GraphViz for debugging DAGs).
https://real-world-plantuml.com/
Everything checked into Git
For the text part you could use pandoc.
In the end you have a pandoc pipeline which mixes your text with your pictures (plantuml) and generates some nice documents