Sequence diagrams, the only good thing UML brought to software development

I've use sequence diagrams a few times. I find any kind of diagram tooling to be a tedious time sink. The resulting output is a talking point at best. Some window dressing for a presentation or internal document. Fluff you add to impress some easily impressed managers or clients. I always feel slightly dirty doing stuff like this. I have UML distilled on my shelf. A signed copy even. Haven't opened it in over two decades. It's obsolete.

Diagrams are communication and marketing assets at best. They are not creative tools. You create them for other people; not for yourself. And it takes a lot of effort to create them. If you measure the value of your time in dollars per hour (as your clients/employer should be doing), a good diagram can be several hours of work. So, it's expensive. A few hundred dollars is nothing.

Next time you see a diagram, ask yourself the question "would I pay 300$ for this thing?". In my case, the answer predictably is "hell no" 100% of the time. Asking the question is kind of answering it. Diagrams are rarely helpful. Either they are way to simple to add much value or way to detailed and hard to understand. There seems no middle ground here. So, you have three or four things with some arrows and labels. Well, yay! Tell me something I didn't know already.

Diagrams are low value window dressing. A literal waste of time and money. I do them rarely, reluctantly, and only when people really insist on them (and I'll push back a little). I find tools in this space tedious and frustratingly slow to use. I have more interesting things to do typically. If I do them at all, they are going to be a quick and dirty job.

It's not just me. Objectively, diagrams are very uncommon in software development these days. They are not part of regular software development processes, clients don't ask for them anymore, the vast majority of projects (and close to 100% of OSS projects) don't have them, etc.

UML is great to clarify situations that are harder to grasp with other communication tools. And by communication, I don’t mean only with other, but also with oneself.

Cerntainly UML is not always the best tool, but I see no point to pretend it’s a garbage toolbox no one should care about except for the only tool that ever helped for the work you had to do.

> Class, component, package, activity and state machine diagrams are all useful ways to model the structure and behavior of a system visually

They're not bad, but the C4 model is a much better approach to high level modelling (while you can still use class diagrams on the lowest level). https://c4model.com/

This has nothing to do with UML. Ad-hoc diagrams or plain text descriptions become outdated at the same speed, which depends only on the level of detail that you put in documentation and not on the format if it. If you cannot keep up with the changes in the code, you are choosing the wrong level of detail, that’s it.

> And it takes a lot of effort to create them.

Have you tried mermaidjs? It's probably related to mermaidchart.com -- I don't know. The first sequence diagram in the article boils down to this:

    sequenceDiagram
      Customer->>Bank: Login request
      Bank-->>Customer: Login approval

with a fancier image for the customer than a box. Try it out at https://mermaid.live (linked from https://mermaid.js.org/)

Or this one, from a service I worked on a couple of years ago:

    sequenceDiagram
      Title: Service Signup
      autonumber
      User ->> App: User enters email address and password
      App ->> Server: Makes API call to register the user
      alt is not registered or already registered
        Server ->> App: Sends a token for authenticated API calls
        App ->> App: Generates unique ID
        App ->> Server: Makes API call to link user's account with unique ID
      else some other error
        Server ->> App: Returns [TODO: add error cases here] error
        App ->> User: Display error
      end

I hated drawing diagrams with a mouse, but when I found mermaid, I started using sequence diagrams everywhere.

> Diagrams are low value window dressing.

It's about communication, as the article said. The people who needs the diagrams the most are often not tech-savvy.