Ask HN: Visualize Software Architecture/Concepts | Hacker News Reader

Ask HN: Visualize Software Architecture/Concepts

29 pointsbiosboiii19 comments

So my dayjob is working in a software project with dozens of teams, hundreds of employees.

Common denominator that nearly everyone knows nothing about software, except some subcontractors who are not part of our processes.

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.

Can anyone of you guys recommend me some tool, or format, to explain software architecture to non-technical folks, gentle-parenting style?

Thx in advance :)

View on HN

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-PlantUML

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.

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.

The problem is that the non-technical people are working as architects.

What do you mean?

- https://excalidraw.com - https://mermaid.js.org

Karpathy also likes excalidraw: https://twitter.com/karpathy/status/1816873021166223397

Excalidraw is my favorite drawing tool for diagramming, by far. I even embedded it directly into an app so you can draw labels for buttons.

Love Excalidraw - simple to use.

I use draw.io as well but also find creating message sequence charts using - https://sequencediagram.org/ 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.

https://www.ilograph.com/

Apart from draw.io I like to use isoflow.io for near isometric diagrams with directional flows as well

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.

https://c4model.com/

Write a code base scanner that traces source of all identifiers.

This can generate data flow diagram.

Run the scanner across codebases, you get entire distributed software's flow.

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 ...

when other people can't understand what you communicated , most of the times, it is fair to say that it indicates your communication incompetence instead of the other way around.

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.

Your API is the person who handles the form. Just ride that analogy, and you should do fine.

Try https://monodraw.helftone.com/

I like gliphy - i can use layers and show each team the relevant information. I can also use links to confluence pages

I also use plantuml a lot

lucid.app

drawio is ugly but free

excalidraw has weird hotkeys

Reply on news.ycombinator.com