I feel like diagrams should not be pretty. For example, colors should convey meaning rather than being aesthetic or artistic choices.

I get that ugly software diagrams are not fun to look at, but to me dressing them up is like adding curves to a line chart - yes it's visually appealing but it interferes with the data being conveyed.

Beauty is useful, but it needs to be the last step. When something like nice people also assume the contents have been polished and so since a lot of work went into thinking about it already it isn't worth the time to question if it is right. You can question if you understand it, but the diagram itself is right and so the problem is you.

Most diagrams have not had that must thought put into them. They should look a little ugly because that implies it might not be right so look for errors.

> They should look a little ugly because that implies it might not be right so look for errors.

Weirdly, prettiness is the bigger red flag for me wrt to error. I see that and feel like more attention was put into that than the underlying information.

Ugly, brutalistic, utilitarian stuff tends to imply a focus on correctness to me.

Nicely presented data can certainly inspire confidence, which might or might not be justified, but I think attractive presentation can be more than just a sales pitch. Ultimately, we create these visualisations to convey information to someone else, so good presentation should help that someone to navigate and understand that information, and it should avoid introducing unwanted bias or ambiguity.

If that means creating an overview of the system architecture for new team members that uses pretty colours and multiple fonts and icons and shaded boxes but that helps them to understand the system more quickly and correctly than an overwhelming page of black-and-white text and arrows, the extra styling has done its job.

You are confusing good and readable with beautiful. A pencil sketch can be readable and good, yet still look like it can be changed. By contrast if you make it look like perfect it will look like it cannot be changed.

Sorry, I don’t understand the point you’re trying to make here. Finding ways to present information that are both functional and attractive — and stay both of those things as the information evolves — can be a challenge, but I don’t believe those are completely independent axes and I don’t think achieving and sustaining both in combination is an unrealistic ideal. Indeed, I’ve spent a significant part of my professional life creating specialised user interfaces for various products that try to do exactly that.

The point is if something looks too polished people assume that polish is all the way. You look at a polished chart different from a sketch. If I show you a napkin sketch of some new idea I have you understand it is new and not well thought out, thus you ask is the big picture idea correct. If instead the same idea is well polished in full color you think the big picture is correct and start looking at details that might need some adjustment. Depending on what sort of feedback you want, you need different types of drawing.

This is true, and why some diagramming packages include "draft" modes that intentionally change the presentation to make it look less permanent/polished looking.

Well, colors can be both pretty and informative.

Had to take Color Theory to get my BFA. We learned things like the "speed" of colors: yellow is the "fastest" and purple is the "slowest". Only a little yellow is needed to balance out a lot of purple. Same for balancing the other colors. You use these balances for guiding the eye (lots of yellow on a purple field).

When you keep this in mind, diagrams or not, then the output will be "pretty" (not jarring) and "informative" (guiding the eye to the most relevant info).

I do really like diagramming tools that have a mode that kinda-sorta looks like a human sketch, though. I feel like it lets me not worry about the thing being pixel perfect.

The fewer right angles, the better: I can just draw shapes and put them in roughly the right spots and it'll look fine.

D2 has a very good layout engine (tala), but its use requires a paid license. The other two engines aren't nearly as good.

https://flowchart.fun/ recently helped me very quickly draw flow charts to understand process of a system. Best thing was how intuitive and fast I could iterate over. And it allows custom css for styling which helped a lot. IMO for flow charts, this is so far the easiest / quickest text based diagram tool.

Thanks for sharing. I love mermaid, and use it frequently. I’ll have to check out D2. I think declarative diagramming is a powerful tool to capture thoughts in a readable way that can be versioned like any other text.

Hi. This is really cool. I tried your example, and it rendered top to bottom instead of left to right (as in the directions).

The very first example: x -> y

I rendered the svg, and then loaded ONLY the svg into a browser window.

I then looked through the whole of the document and tried to find how to align the output... and couldn't find out how.

Since the linked instructional was diverging from real life results, I stopped using it. :(

If you know how to fix it or could update the directions to ensure reliable output to the directions... that would go a long way for visitors like myself :)

Edit: did a google search for "d2lang connection left to right" and ended up here: https://d2lang.com/tour/layouts/

which may be helpful to you for the question I surfaced as it isn't linked in your overview docs :)