C4-PlantUML

It may be even simpler: plain markdown files that explain architecture including C4 diagrams generated from text using plantuml (automated via invoke/fabric/whatever). Plantuml includes C4 in stdlib https://github.com/plantuml-stdlib/C4-PlantUML

What sort of maps are you wanting to build? https://c4model.com/ seems to be the more popular standard for this style at the moment. https://github.com/plantuml-stdlib/C4-PlantUML makes this somewhat easy to code out. (And I think most cloud providers have addons for it.)

https://c4model.com/ https://en.wikipedia.org/wiki/C4_model Level 1: System context diagram Level 1, a system context diagram, shows the software system we are building and how it fits into the world in terms of the people who use it and the other software systems it interacts with. Level 2: Container diagram. Level 2, a container diagram, zooms into the software system, and shows the containers (applications, data stores, microservices, etc.) that make up that software system. Technology decisions are also a key part of this diagram. Level 3: Component diagram Level 3, a component diagram, zooms into an individual container to show the components inside it. These components should map to real abstractions (e.g., a grouping of code) in our codebases. No need to go deeper considering your audience. https://github.com/plantuml-stdlib/C4-Pla

Third this. Don't look any further, just do it! Also, PlantUML + C4 is like peanut butter & jelly: https://github.com/plantuml-stdlib/C4-PlantUML I'll gladly give up control of layout, and accept some ugliness, to never again have to worry about dragging boxes and arrows to be pixel-aligned, and then do it all over again when I add another box... It looks like Mermaid has C4 support too: https://mermaid.js.org/syntax/c4.html

FWIW You can do a C4 model using plantUML diagrams [1] imported directly into RST markdown (or inline, fwiw, but that makes live preview harder) 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". [1] https://github.com/plantuml-stdlib/C4-PlantUML

PlantUML also has a nice library for C4 model diagrams available [0], which I've found very useful. [0] https://github.com/plantuml-stdlib/C4-PlantUML

The C4 model (https://c4model.com/) is great for architecture diagrams. You can use different tools to generate them. Here are the ones I've been using: - https://github.com/plantuml-stdlib/C4-PlantUML - https://structurizr.com/ (by Simon Brown, the creator of the C4 model)

You can use C4 with PlantUML. https://github.com/plantuml-stdlib/C4-PlantUML

> onboarding docs 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-b

It can be a bit clunky setting up the jar (or hosting it yourself), but it's still the best worst option. It scales pretty well and can draw some very complex flows, while still giving you the best in just plain ole text editing. 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. https://github.com/plantuml-stdlib/C4-PlantUML

Good answers here already. 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/ [1]: https://github.com/plantuml-stdlib/C4-PlantUML

If you're interested in diagramming system architecture in a top-down fashion, I'll pile on another recommendation to check out the C4 model[0]. 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 probl

Maybe plantuml https://github.com/plantuml-stdlib/C4-PlantUML with the c4model plugin helps (https://c4model.com/). Using plantuml includes you might be able to have some kind of overview plantuml picture, where you can click on the included to see the detailed contexts. 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

PlantUML with the C4 extension https://github.com/plantuml-stdlib/C4-PlantUML

This (icepanel.io) is just a graphical editor (with some very nice functionality) for C4 Model diagrams: https://c4model.com The actual standard is quite light weight, which is its main selling point. The whole premise is that many teams find rigorous standards like UML and Archimate too heavy and thus resort to basic boxes-and-lines diagrams. C4 essentially says "take your boxes-and-lines and put full sentence descriptions on everything". Combine that will successive levels of detail, and you have the C4 standard. You don't have to give up diagrams-as-code because you can create C4 diagrams with PlantUML [0] or using the C4 specific DSL [1]. [0] - https://github.com/plantuml-stdlib/C4-PlantUML [1] - https://github.com/structurizr/dsl