[zoogeny]

One problem with these tools is that even if you manage to get a good layout for a document then as soon as you need to add/remove/update then you have to wrestle with them all over again.

I've used a few of these code-as-diagram products because I dream of a world where technical documentation, including diagrams, are part of the source code of a project. But my experience is that getting acceptable layouts, especially for external distribution but also just for internal use, is arduous.

And that frustration leads to at least two possible undesirable outcomes: the diagrams become unreadable or the diagrams become unmaintained.

To be honest, the idea of code-reviewing the documents during check-in is also a myth. In general the diffs on these kind of documents are extremely difficult to grok. It is almost impossible to meaningfully check the document is correct without rendering it and reviewing the output.

It is the kind of thing I really wish worked. Maybe one day it will become a solved problem.

[dangets]

I've thought the same quite a bit.

On one end of the spectrum you could use something like SVG if there were standard or dominant tools used to import/export, but then you lose the ascii readability benefit of tools like this, dot, or d2.

It'd be nice to have a mixed text & GUI editor for something like Pikchr diagrams.

https://pikchr.org/home/doc/trunk/homepage.md

https://d2lang.com/

[zoogeny]

Something in the direction of SVG is probably correct. I like the idea of having arbitrary paths available. One common annoyance with existing tools is that there is sometimes a lack of shapes and colors that express what I want. I find the same even with Google's rudimentary drawing tools.

It may be the case that these diagraming tools are aiming to be too high level. But where the middle ground lies I am not too sure. It is nice to express high level concepts like "Actors" or "Process" or "Class". And it is nice to have convenient syntax for things like UML sequence diagrams. I don't think it would be an equal exchange to give me rectangle and line drawing primitives since now I'd have to manage the connections by hand. And there would be no semantic meaning in such text formats, even if you managed to retain "readability".

But on the other hand ... to get the diagram solutions into a visual format I like I tend to lose the readability anyway. If you have several boxes with many connection - even reading the text becomes difficult. It is hard to keep the connections in your head once they get 2 or 3 hops deep. And you end up with 15 lines of connection spam, like "EntityA -> EntityB", "EntityC -> EntityB", "EntityA -> EntityD". And you end up trying to manage hierarchical relationships, fussing over what is the correct order to declare things, like manually doing your own dependency resolution. So maybe strict readability isn't really even a property I can expect to maintain.

I really hope it gets solved one day.

[jrowen]

It seems like a situation that would benefit from separating the logical/structural definitions from the layout/presentation rules, much like HTML and CSS. The structural side would be clean and easy to maintain and all the fiddly presentation stuff would have space to be specific. Constraint-based layout rules a la flexbox would seem useful. Has anyone tried that approach?

Edit: You're probably still going to have to render it as part of the review for non-trivial changes but when the visual result matters I don't see any way to avoid that.

[MilStdJunkie]

If you don't mind my asking, what aspects of "acceptable layout" is usually the first to get busted? Do the fonts overstrike? Does it shrink down so small the lines don't render? Is it just that all the boxes get thrashed in a blender and the diagram looks completely different?

I'm extremely excited about using WireViz[1] to automate wiring harness diagram creation, and if I can, I'd like to know the speedbumps before I hit them. I'm thinkin generous linking between diagrams will be one path - keep the individual diagrams fairly small in scope, link 'em together.

[1] Project:: https://github.com/wireviz/WireViz SandboxP:: https://kroki.io/#try [select Diagram>WireViz]

[zoogeny]

I have two main complaints that jump to the top of mind.

The first is lines and when they merge and when they cross. Not all lines from two separate boxes to a third box ought to merge, but some should. Crossing is inevitable in most complex diagrams but expressing where the crosses ought to happen is not something I have had any success with.

The second is that some diagrams are like a story, with a beginning a middle and an end. Using horizontal, vertical and even diagonal relationships visually can be important. Keeping that story clearly organized has always been a challenge and even requires some iteration when doing the drag-n-drop thing. Rarely does the story of the diagram just happen to pop out using the default placement algorithms of any text-to-diagram tool I have used. And so I find myself tediously massaging the order of statements or whatever crude controls I'm given to painstakingly move boxes into some semblance of the story. And then, once I've managed to convince the diagram to be as close as I can to what I envision, I realize I missed a key component or connection.

The last thing I'll point out is more a preference. In general, the output tends to be quite ugly to my eye. There are times I have been responsible for generating systems diagrams for potentially big deals. In those cases we want to put the best foot forward to external entities. There is something uncanny valley, or like generated text-to-speech in the appearance of the documents that can be undesirable in many contexts.

[jldugger]

In my experience with graphviz, the two layout problems are:

1. the lines are not distinct -- they can bunch up and overlap, making them untraceable 2. Logical groupings are hard to maintain unless they are highly connected.

[lenkite]

These tools should ideally chosen a simple, known syntax like S-expressions or XML.