So my dayjob is working in a software project with dozens of teams, hundreds of employees.<p>Common denominator that nearly everyone knows nothing about software, except some subcontractors who are not part of our processes.<p>So in every meeting I need to explain simple concepts like what the API of the service I designed is going to in the context of our whole software context, and currently this is done by fiddling around on draw.io and with my hands and feet.<p>Can anyone of you guys recommend me some tool, or format, to explain software architecture to non-technical folks, gentle-parenting style?<p>Thx in advance :)
<a href="https://c4model.com/" rel="nofollow">https://c4model.com/</a><p><a href="https://en.wikipedia.org/wiki/C4_model" rel="nofollow">https://en.wikipedia.org/wiki/C4_model</a><p>Level 1: System context diagram<p>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.<p>Level 2: Container diagram.<p>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.<p>Level 3: Component diagram<p>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.<p>No need to go deeper considering your audience.<p><a href="https://github.com/plantuml-stdlib/C4-PlantUML">https://github.com/plantuml-stdlib/C4-PlantUML</a>
Do they really need (or care) to know the underlying architecture? Typically the non technical audiences I've worked with care more about how it solves their problems, how much it costs, who responds when something goes down (and how long it takes), what your pros and cons are compared to the competitors, etc. They typically glaze over at the architecture part or take a picture of it and send it to the devs afterward.<p>Why do they need to know what an API is, rather than what your integration will do for them and how it works with their existing system and process? That kind of stuff belongs in the appendix, at a very high level of abstraction (ie your software sits here, ours is here and connects to it, this is your workflow before and after). If you're going into C4 territory and explaining your whole stack, that's probably way too much detail that's not relevant to them and also may change later anyway. My 2c is to focus on the what and why, less so the how. Tell them their devs can reach out to you separately for a technical deep dive if they need it.
I use draw.io as well but also find creating message sequence charts using - <a href="https://sequencediagram.org/" rel="nofollow">https://sequencediagram.org/</a> very useful for the teams to understand the workflows. Rather MSC is something I have made mandatory for certain complex workflows which involve multiple apps and services.
C4 modelling (with associated diagrams using whatever tools) can be powerful, part of the value is that they help capture the nested and relational nature of many software systems.<p><a href="https://c4model.com/" rel="nofollow">https://c4model.com/</a>
Write a code base scanner that traces source of all identifiers.<p>This can generate data flow diagram.<p>Run the scanner across codebases, you get entire distributed software's flow.<p>There will be loose ends because of urls formed from configurations. It's fine, make it work, then improve.
I've used draw.io, mermaid using polyglot in vs-code, obsidian canvas diagrams, and gherkin with a cucumber plug-in for visual studio (req n roll ?).... non-technicals still don't get it, but at least they know they didn't get it ...
Explain it in terms of paper forms and bureaucrats. You've got a form that gets submitted, and replies come back in other very structured forms.<p>Your API is the person who handles the form. Just ride that analogy, and you should do fine.