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