Nomnoml (opens in new tab)

You have to learn UML because of the stupid arrows. Compare it to something like this which acknowledges the fact that nobody is going to casually memorise 10 different styles of arrow just to read occasional UML diagrams:

https://buck2.build/docs/concepts/concept_map/

Much better.

through that's kinda true for a ton of tooling using the word "UML"

and in many case you also somewhat want something which is less precise (and verbose) then UML theoretically is

[1]: https://d2lang.com/

The underlying js library will render straight to an HTML canvas or to SVG from a Node.js program. You can run it from the command line if you want to.

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.

  [Pirate|
    [beard]--[parrot]
    [beard]-:>[foul mouth]
  ]

  [Pirate|
    [foul mouth]<:-[beard]
    [parrot]--[beard]
  ]

  [Pirate|
    [beard]
    [parrot]
    [foul mouth]
    [foul mouth]<:-[beard]
    [parrot]--[beard]
  ]

I struggle to think of what this might be without it turning into some other natural language. For example, the tool that’s used to convey intentions and ideas in these comments is written English, which certainly has its own structure.

Yeah, it's absolutely horrible when the GitHub link is in the bottom right rather than the top right. Completely unforgivable. Geez.

Do (Free|Net|Open)BSD and GNU tools qualify as open source? No GitHub link as far as the eye can see :)

There's actually another category. Open source software with paid plugins. I always wonder what happens when someone adds similar functionality to the open source version.

It's nice to have your diagrams as readable code which you can check in with the rest of your git repository and embed in READMEs, and the syntax is really intuitive and easy to learn. I haven't made the comparison with this particular tool yet, but in general I'd recommend this practice of including diagrams with your docs.

You state this like a fact. A GUI might be your personal preference but markup is preferred by many. It takes me an order of magnitude longer to learn where all the buttons are than it does to internalize markdown syntax from a few good examples. In a GUI you spend time futzing around with visual details, In a markup chart you spend time building and communicating a coherent mental model. The difference in output quality is apparent to me.

There's an analogy to programming: sure we have visual programming tools but who uses them? they break down when things get mildly complex. A markup driven charting tool lets me edit in the comfort of my chosen IDE, check it into source control to collaborate, renders live instead of checking in an image artifact, and has clearly-defined semantics (ie not just a pile of incoherent boxes and arrows). IMO, it's superior in every way except fine-grained control of the layout (which is a fine tradeoff for me - I want my readers to focus on content - consistency is more valuable than styling). If your purpose is communicating complex ideas (not making a pretty picture) markup-based charts have some distinct advantages that you just can't get from a point-and-click interface.

On the contrary, I use drag&drop tools for very simple diagrams but prefer using PlantUML for anything complex because its text-based interface makes it easy to generate, diff or store in a git repository. The best of both worlds would be a text-based tool to hold the semantics of your graph, and then a drag&drop interface to fix the layout.

We don't have many options of approved diagramming software where I work though. Omnigraffle which I don't care much for, and Visio which doesn't work on Mac. Maybe I'd have a different opinion of we had something proper.

For random boxes and arrows I do typically go for Excalidraw though.

1. You can build tools to automatically generate these diagrams from existing software quite easily. I've used tools like this to generate diagrams that were impractical documentation (150+ sheets of A4 when printed), but showed class or module dependency hotspots in a way that would have taken weeks to understand from the code alone: a picture speaks a thousand words, and getting your code to give you a picture is useful.

2. You can version control them - and see change history - more easily through a markup/code approach than a GUI approach. When teams collaborate over a complicated piece of design, being able to see who contributed what and when in a diagram is as useful as it is seeing it for a piece of code. I'd argue the first responsibility of a programmer in a modern team is to communicate, and to do so in a collaborative fashion. Code, tests, documentation, should allow easy collaborative understanding, editing and iteration. Diagrams that don't have editable markup make this harder in a small way.

3. The semantics of the markup actually make you think through what it is you're trying to express. It's easy to draw a line connecting two shapes but what does that line actually mean? I find when I'm typing up markup for a diagram, this becomes something I more consciously consider.

4. A markup standard means there is likely to be multiple tools that support the reading, editing and creation of the artifacts you create. Some people feel it's easier to use a WYSIWYG word processor, but I think we can all agree that Markdown is a useful innovation that has stimulated some experimentation and development in the text editing domain.

5. Most "hand-drawn" GUI-based diagrams look ugly (most programmers can't design diagrams well), but using an algorithm to make layout choices provides consistency and better layouts.

6. Many "hand-drawn" diagrams are full of style inconsistencies. With a markup + parser = diagram approach, you can enforce a house style, update that style easily, and everybody's diagrams in a doc look aesthetically similar rather than each individual's personal preference on line weights and arrow styles. It's a bit like separating HTML and CSS - hard to do in a GUI-only approach. In larger teams with a dev wiki, all the diagrams looking similar is just nicer.

YMMV, but I'd give this approach serious consideration - this tool looks great, but there are others, and it's worth evaluating them if one doesn't impress you. I'm a graphviz guy, but I might consider looking at this more closely.

Look at the popularity of Markdown, a syntax that is just "simple html but it's easy to read in plain-text form". Or YAML, which is just "JSON and XML that doesn't make your eyes bleed, but has the worst type-inference ideas ever".

Yes, GUI tools can help. Doing image-links in Markdown is a PITA. Ditto good-looking tables. But still, the idea of "human-friendly-text-first" formats is valid.

Doing the same for UML just makes sense to me.

Now obviously there are implementation details I disagree with, both in the format and the renderer. But the idea is sound.

One day, someone on our team had the brilliant idea to log the state of the program as a dot graphviz text file and just render it with the tool. Our debugging effort was instant all of a sudden.

Sometimes these tools are amazing at visualizing data more than at building diagrams. It's surprisingly easy to generate valid text files programmatically. Note that I'm talking in general about this class of tools, not nomnoml specifically.

Yeah, the problem with these sort of layout algorithms is that they don't have a sense of proportionality.

I wonder if LLM can do this better. I've tried with 5 relations from this example one and ChatGPT comes up with this:

    Place "Jolly Sailor" at point (1, 1).
    Place "Pirate" at point (2, 1).
    Place "rum" at point (3, 2).
    Place "mischief" at point (2, 0).
    Place "Marauder" at point (3, 0).

[0]https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

And I think they’ve gotten to the point where “how can LLMs change this workflow” is a much more impactful question than basically any other UX improvement

If you create something from the perspective of "I had to make this on my unpaid spare time..", then requests for additional work do seem annoying.

But is that the case here?

If I made a utility I thought other people could also benefit from I'd personally be open to suggestions. I'd ignore a lot of them, but every now and then someone requests something interesting that sparks motivation to expand the utility.

HOWEVER...

I've had a few people who say things like "OMG. YOU MUST DO IT THE WAY I THINK YOU SHOULD DO IT" or "ADD THIS FEATURE OR YOUR NOT A REAL OPEN SOURCE CONTRIBUTOR." And that is definitely annoying. I have a thick hide and don't mind just ignoring those people, but that shouldn't be the default assumption. The people who work on open source projects are people, so don't be a pushy jerk when you're requesting features from FLOSS projects.

ALSO...

Let people revel in the approval of their peers before pointing out things you would have done differently. This is a cool bit of kit.

I've been maintaining open source software for two decades now, and I still love it when people ask for more stuff. It signals engagement and satisfaction and gives me very concrete directional guidance around where I should take my software.

I'm under no obligation to deliver on those requests.

My day job pays my bills, my open source stuff brings me joy.

Try to launch a free service for consumers and experience how they are entitled to stuff just because you offer this service.

Miro and others, I am always thinking visually. It's another step removed from the real thought process.

As you point out, these systems sometimes produce difficult to read diagrams. For particularly important communications, I will re-draw these in draw.io, or a similar sort of tool. But then I am thinking more about presentation, rather than relationship design and the tool is better for the job.

1. I want changes to the diagram to be peer reviewable and understandable. 2. I want something else to manually lay out things, rather than have to adjust it personally on every addition or change. 3. I want a parsable structure I can feed into grafana or similar, so I can decorate the graph with metric data. It seems like it would be cool to have a graph of RPC calls and which links were red.

And personally, if you're going to suggest an alternative, Miro is not the one. Irritating SAAS nonsense