News for hackers. Stuff that matters.
Re:Ask HN: Guidelines for making clear architecture diagrams by shinkim0914 on Wednesday May 01, 2024 @09:38PM (#40231850)
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.

Re:Ask HN: Guidelines for making clear architecture diagrams by Brajeshwar on Wednesday May 01, 2024 @11:24PM (#40232380)
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).
Re:Ask HN: Guidelines for making clear architecture diagrams by langnutty on Thursday May 02, 2024 @11:08AM (#40237185)
I never figured out how to make a valid password.
Re:Ask HN: Guidelines for making clear architecture diagrams by contingencies on Thursday May 02, 2024 @01:47AM (#40233074)
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.

Re:Ask HN: Guidelines for making clear architecture diagrams by langnutty on Thursday May 02, 2024 @10:57AM (#40237058)
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…