UML has been a joke among most software developers I know for years. In my first job I was subjected, briefly (but not briefly enough), to the last gasp of the 2000s-era dream of generating all the important code from modeling diagrams.¹ Never wholly banished, UML persisted mostly in corners of software development best described, I think, as “enterprise-tastic”. I occasionally see it crop up in design documents and: laugh in mild disbelief.

And yet.

Last month I opened a pull request which made extensive use of UML in its description to clarify what in the world was going on. (It worked: a collaborator noted: “it was very very helpful for quickly building context here”.) A few months ago I published an ARCHITECTURE.md for Glint which included sketch-style drawings². This fall, I built a similarly sketch-style diagram to explain the different layers of a modern web meta-framework to non-web-specialist engineering leaders at LinkedIn.³ Only one of these was using UML, strictly speaking, but all of them were UML-adjacent, and the one which needed something like UML really needed something like UML.

What changed, for me? Well… the combination of the existence of Mermaid.js and its integration with GitHub’s Markdown rendering, plus contexts which needed the illumination which only a diagram can bring. Sometimes, indeed, a picture is worth a thousand words. When I started writing up the pull request description where I ultimately ended up with a really horrifying UML diagram (not the diagram’s fault: it was representing a really horrifying bit of organically-grown type hierarchy in Ember.js), I realized that there was no way anyone would be able to follow it simply by reading the thousand words it would take to describe.

That’s not an exaggeration: In this case it would have literally taken a thousand words to describe it — I would know, because I started out by writing about a quarter of that before I bailed and made the diagram — and one picture did the trick!

Tratt writes:

With the benefit of hindsight, I think UML had quite possibly reached not only its actual, but also its potential, peak in 2000: as a medium for software sketching, people only ever needed the basics from it.

UML is still a poor tool for a lot of the design ends to which I occasionally see it put (if a picture is worth a thousand words, a TypeScript interface declaration is often better than either!) but when all you need is a lightweight sketch of some relationships so people can understand what you’re talking about, rather than an end-to-end system design expressed in nauseating detail… UML is great, actually! And maybe it is set up to make a bit of a comeback, in the areas where it is fit for purpose, as I recently found.

All of which is to say two things about tools for software development — UML and others:

1. Pushing them past what they are actually good for not only does their users a disservice; it can make it hard for people who could benefit from them even to see their value.

2. All sorts of factors can bring a tool back around when it has fallen out of favor for whatever reason — good or bad. The work of a handful of hackers making Mermaid.js, and then GitHub adding support for it, might do more to spur (re)adoption of UML in the 2020s than all the standardization efforts of the 2000s did.

---

Notes

1. The same era saw that same organization seriously flirting with IBM Rational Rhapsody: a solution in search of a problem if ever I have seen one, but/and one directly tied to this same dream of UML everywhere. This was in 2010! Even most of the die-hards had given up by then. To call the organization I worked for at the time dysfunctional is to insult dysfunctional organizations everywhere. But this is a rant for another day. ↩︎

2. generated with Excalidraw, if you’re curious. ↩︎

3. which I hope to publish both a blog post and a YouTube video about sometime in the spring ↩︎