I have come to the conclusion there are two kinds of audience and two kinds of diagram, abs they almost exactly overlap
1. Engineering diagrams, explaining concepts to other engineers who are using the diagram as a jumping off point to deeper explorations
2. "Business" diagrams - the sort of thing we want to see in a Medium article or presentation. The style and correct placement matters far more than engineering.
The first is very amenable to markdown style production - often we want to spend no more than a few minutes creating the diagram. We get (60?) 80% of the way there with 20% effort.
But with every markdown approach I have tried the remaining 20% is flat out days of work. There is almost always a need to place that box there and have this one below and to the right and dammit the layout engine will not agree.
What I would ideally like is a combo - markdown to get me most of the way there, and then drop into some vector format that lets me tweak.
Have you tried PlantUML? It provides means of adjusting the layout.
I use it often, most of the time the adjustment is good enough for engineering communication within minutes of adjustment.
It could be better if there is more cohesive documentation of its support for the adjustment.
I had to search on Google many times to figure out how to add the adjustment.
The adjustment consists of directives of placement and direction of links, the length of links, grouping of notes, etc.
I feel that it's very promising with more popular support.
I have not seen the layout adjustment features, but I’ve very recently been using pandoc and plantuml for all my design docs at work. I find it to be highly productive, though I still end up uploading the resultant word file to one drive for collaboration and review since that’s what everyone else uses.
Is there a javascript/clientside library which implements the plantuml visualizations? Viz.js is linked on plantuml page but it appears to be archived.
Embed diagrams in source code comments; build script greps through and writes out an SVG. A caveat is that to be adequately productive, you need rectangle-oriented editing, such as with Emacs’ “M-x string-rectangle”.
I agree. I looked at migrating our technical documentation out of MS Office documents into some diffable format and it were the diagrams that killed the initiative.
Tables are a pain, but most technical docs do not require rowspan and other things that are impossible to maintain in Markdown/reST/Asciidoc.
Diagrams are just a shitshow. PlantUML is the biggest player, and it tries to do the right thing by separating semantics and presentation, but kinda fails when your diagram grows too large.
I wish there was some tool that you could feed three separate human-readable inputs:
- styles, which let you define what your elements look like
- semantics, which let you describe your elements and relationships
- layout, which lets you manually rearrange the elements on your diagram (and is generated by a WYSIWYG tool)
Pikchr generates nice diagrams, but it's an all-in-one dialect. At least when I am reading well-written PlantUML I can understand the meaning of the diagram without seeing the rendered image.
The tool in the OP is nice, but it doesn't let you describe the layout at all.
Ilograph fulfills 2 out of 3: diagrams are broken up into a model (resources) and perspectives (their relations). The layout is always automatic, though. As a plus, though, this allows them to be interactive and dynamic.
I would love to see an integration with excalidraw where you write text to seed the diagram and then do the touch ups with something like excalidraw. That would solve I think your workflow.
Please give me a combination between Excalidraw and Graphviz, with stylesheets, and layouts generated via a straightforward Python API, immediately displayable in a Jupyter notebook, with a display widget having hooks to move items around, giving auto-updating a Python property dict.
diagrams.net (formerly draw.io) have an xml format that seems fairly open and they can also read/write a bunch of other formats (see here https://www.diagrams.net/blog/import-formats ) so something that gives you their xml format as a starting point might make sense.
Just use SVG plus d3. Only trick is coming up with a pipeline to convert this into a pdf or png so that it is easier to use outside the web.
I only throw in D3 because it does have some features which make SVGs more maintainable and easy to write, but I've written many SVGs by hand over the years and it really isn't nearly as bad as many people think it is. I suspect a lot of people think it is very difficult because they only look at the terrible SVGs generated by GUI tools.
I would recommend starting with plain SVG and then exploring D3 after. It's best to think of D3 as a combination of jQuery and a geometry library.
For starting with SVGs, just look for a simple tutorial like https://www.w3schools.com/graphics/svg_intro.asp to get a simple template, but focus on learning the path element. The path element is both foundational to a lot of custom SVG stuff and isn't too complicated, sort of like the Basic of graphics.
I'm curious if you could get from an 80% solution to a 90% solution by just adding some markup to say things like, "This node should be to the left of this other one?"
Often I use invisible subgraphs to accomplish this sort of thing in GraphViz, but the markup for doing so is complicated and non-obvious.
I recently stumbled over a project which tries to do such an approach for graphs in scientific papers, to avoid people manually editing them and them getting disconnected from data sources. They do it by offering export of modified code generating the tweaked variant: https://pylustrator.readthedocs.io/en/latest/
agreed it would be nice if the markdown just generated a standard svg that you could then edit, or even just an html canvas where you can drag them around a bit more and add some color before exporting as an image
1. Engineering diagrams, explaining concepts to other engineers who are using the diagram as a jumping off point to deeper explorations
2. "Business" diagrams - the sort of thing we want to see in a Medium article or presentation. The style and correct placement matters far more than engineering.
The first is very amenable to markdown style production - often we want to spend no more than a few minutes creating the diagram. We get (60?) 80% of the way there with 20% effort.
But with every markdown approach I have tried the remaining 20% is flat out days of work. There is almost always a need to place that box there and have this one below and to the right and dammit the layout engine will not agree.
What I would ideally like is a combo - markdown to get me most of the way there, and then drop into some vector format that lets me tweak.