Ask HN: Visualize Software Architecture/Concepts

29 pointsbiosboiii1y ago19 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 :)

Ask HN: Visualize Software Architecture/Concepts

29 pointsbiosboiii1y ago19 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.

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 :)

19 comments

19 comments · 14 top-level

solardev1y ago· 2 in thread

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.

biosboiiiOP1y ago

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

solardev1y ago

What do you mean?

keisku1y ago· 1 in thread

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

vismit20001y ago

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

eternityforest1y ago· 1 in thread

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.

desselbane1y ago

Love Excalidraw - simple to use.

DrDeadCrash1y ago· 1 in thread

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

android5211y ago

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.

tinix1y ago

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

wishpal1y ago

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.

vladsanchez1y ago

https://www.ilograph.com/

iAkashPaul1y ago

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

Glimjaur1y ago

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/

imvetri1y ago

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.

mikewarot1y ago

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.

constantinum1y ago

Try https://monodraw.helftone.com/

fiftyacorn1y ago

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

yamumsafknho1y ago

lucid.app

drawio is ugly but free

excalidraw has weird hotkeys

j / k navigate · click thread line to collapse

19 comments

19 comments · 14 top-level

solardev1y ago· 2 in thread

biosboiiiOP1y ago

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

solardev1y ago

What do you mean?

keisku1y ago· 1 in thread

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

vismit20001y ago

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

eternityforest1y ago· 1 in thread

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.

desselbane1y ago

Love Excalidraw - simple to use.

DrDeadCrash1y ago· 1 in thread

android5211y ago

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.

tinix1y ago

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

wishpal1y ago

vladsanchez1y ago

https://www.ilograph.com/

iAkashPaul1y ago

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

Glimjaur1y ago

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/

imvetri1y ago

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.

mikewarot1y ago

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.

constantinum1y ago

Try https://monodraw.helftone.com/

fiftyacorn1y ago

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

yamumsafknho1y ago

lucid.app

drawio is ugly but free

excalidraw has weird hotkeys

j / k navigate · click thread line to collapse