HN Explorer

Ask HN: Guidelines for making clear architecture diagrams

61 points by pinkmuffinere ↗ HN
I’m new to making software diagrams. I come from a mechanical engineering background, and when drawing free body diagrams there is a set of conventions commonly followed to make a clear diagram. Is there such a set of conventions for software architecture diagrams? I googled briefly, but seem to be getting low quality articles, most of which are pushing a product :(

24 comments

[ 3.2 ms ] story [ 52.7 ms ] thread
warrenm
~25 years ago ... I would have UML or, more classically, an ERD or even a flow chart

The only diagrams I have seen in the last decade or two, though, have been Visio (or a similar tool) meant to explain the product's functionality (including where and how it scales) to customers, PS folks, etc

glawre
I like the C4 Model as a guide on the different levels of abstraction that you might need for your system.
pinkmuffinere
Oh thanks, this looks like the kind of thing I was searching for — will read up on it
NomDePlum
Second this.

Reference for anyone looking I to it: https://c4model.com/

There is also quite a lot of options for helping create these diagrams. I've found https://structurizr.com/ to be the best of what I've tried so far.

Onawa
I like the idea behind structurizr, but I found the syntax to be too constraining and the tooling around it to be difficult to deal with. That was 2 years ago though,maybe I should revisit it.
NomDePlum
Not sure it will have changed that much.

There are definitely limitations, for me being able to encode and version control diagrams and system documentation alongside a codebase made the tradeoff worth it.

Onawa
As far as guidelines, I have spent time looking as well an never came away with a good answer. One useful website for comparing some of the best tools is https://text-to-diagram.com/. My personal favorite is D2. Still lacking a few layout features that I want, but it gets me 90% of the way there. The syntax is great for projects big to small, and it strikes the perfect balance between "create a diagram fast" and "feature rich". But in terms of actual guidelines, I would agree with another user that C4 actually tries to lay out some sort of guidelines.
contingencies
Conventions exist but they're mostly crap (eg. UML).

Along the KISS principle, boxed elements with connecting lines are the best (simplest, most universally understood, least amgbiguous). In mathematical terms they are an 'undirected graph', a 'directed graph' is the same but with directionality ("arrows") on the links between nodes. https://en.wikipedia.org/wiki/Graph_(discrete_mathematics) The standard toolkit since at least 1991 for defining these in software is https://graphviz.org/

If you need to show the interaction between elements over time in a distributed or complex system, the standard is the message sequence chart https://en.wikipedia.org/wiki/Message_sequence_chart. The best (ie. most long term stable) tool for this be https://www.mcternan.me.uk/mscgen/ which is graphviz-inspired.

There are a plethora of latter-day derivatives such as web-native versions, stylized versions, etc. but these are all functionally irrelevant if you want to be clear, portable and maintainable. Lists of them are frequently posted to HN. The basic workflow is "want to communicate something", "define in text" (which can be done by code), "have image generated", optionally go back and refine.

<neckbeard-yells-at-cloud>The core problem with using web based services, as less experienced / more youthful respondents will suggest, is that they appear and disappear like the javascript frameworks they tend to be built on and thus are a poor match for nontrivial projects with potential medium to long term maintenance and availability requirements. The core problem with Visio and Visio-inspired solutions is that they are WIMP https://en.wikipedia.org/wiki/WIMP_(computing) based and thus tend to require manual clicking and placement which is tedious at best and totally unsuited to any at-scale / automation-related requirements.</neckbeard-yells-at-cloud>

There are also advanced features of these tools which can create complex diagrams like tabular protocol structure diagrams or database structure diagrams, clickable versions, color highlights, and SVG interactive diagrams.

icedchai
There are few standards and there is also definitely some art to it. If you include too much detail, it's confusing and busy. If you include too little, it may not convey anything useful. You should also really need to know your audience. Is it a potential investor, a B2B customer, or another engineer? All these may ask for "architecture diagrams" and mean something totally different.
aledalgrande
After years of using Visio/Plant UML, or similar products that allow you to write clear charts, I am enjoying the freedom of constraints that Excalidraw gives you. It feels a lot more like whiteboarding somehow. Now they have an AI gen feature to kickstart your chart as well. Give it a try. In terms of types of diagrams I create, it's mostly flow or sequence diagrams, but they are not super clear cut.
lemonwaterlime
Also an engineer doing software. The best book I’ve found for this is “Documenting Software Architectures” by Clements et al. It’s a lot but it shows different reasons to use different styles of diagrams and when they are appropriate. For instance, when it comes to creating diagrams for certain stakeholders versus others or when the system is structured in a certain way, certain diagramming techniques would be better than others.
shinkim0914
I'm the founder of a startup that makes a diagramming software for engineering team called Eraser.

If you want a codified set of rules that you can mechanically apply, I would look at UML and C4. However, I'd argue that the frameworks are overkill for the vast majority of engineering diagram use cases.

For the general scenario where you're just trying to communicate a technical concept clearly without spinning your wheels a lot, here are a few tactical things I'd recommend:

1. Pick the right diagram type for the job. Sequence diagrams are great for API documentation, ERDs are great for database schemas, flow charts are great for user flows, data flows and logical flows.

2. Use icons where possible. A database icon, a S3 bucket icon, a cylinder shape are all a lot more expressive and easier to grok than a rectangle with text inside that says "database".

3. Focus on the nodes, groupings, and connections. That's really all there is to a diagram if you break it down. If you just make a list of nodes, groups, and connections that you want to represent, the diagram will almost just draw itself.

4. If you're looking for a quick way to start jump start a diagram or looking for inspiration, try AI tools to see how far they can get you.

Brajeshwar
Eraser, https://eraser.io/ looks awesome. I signed up but had to try a few times with the Passwords (mine was a 42-character with all the jazz generated by 1Password).
langnutty
I never figured out how to make a valid password.
contingencies
1. Yeah.

2. Strong disagree. IMHO icons in diagramming are obsolete for most purposes (smacking of UML and over-wrought database diagrams) and are likely to lead to confusion for the majority of viewers who - at best - aren't quite sure what you exactly mean in this particular case.

3. Which is what graphviz is for. It literally draws itself. Subgraphs are the groupings.

4. I would instead suggest modifying an existing graphviz .dot file, or man dot.

langnutty
Re: 2 I would like a large icon and small text that confirms my intuition about what the icon means. The icon thereby eventually becomes part of my lexicon.

I don’t even see the text, I just see database, load balancer, Redis cache…

flarg
There is. UML diagrams for software, Archimate or C4 diagrams for architecture, value stream for process performance. But depending on the audience you may end up needing to use simple box and line diagrams and they work well too. Draw.io is probably the best drawing tool out there and has enough libraries of shapes to get you started.
bboreham
Might seem obvious, but “don’t try to express everything one diagram” is some of the best advice I could give.

I like the idea of breaking down by Viewpoints and Perspectives, from the book Software Systems Architecture.

https://www.viewpoints-and-perspectives.info/

pvdoom
- Be very mindful of the "level of recursion" you are trying to express - i.e. how many trees to include when it should be a forest.

- Look into the C4 model - that is great for expressing architecture.

- Have a Miro board with multiple versions and working charts.

- Make at least one that reflects the full process, and one chart that reflects the relationships between components.

- Keep it simple, and avoid creating DoD style monstrosities. if you find yourself in that situation it means either you are mixing up recursion levels, or are not very clear on the purpose of the chart and the audience.

- Boxes and arrows are enough

- I personally have benefited from UML style charts, others hate them.

- Domain Driven Design and Event Storming style maps are also very clear way to express things.

- Most importantly - remember that an architecture is not a static thing, but a living, changing and ever-evolving thing. Like a garden.