3 ms·

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 wind

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.

self 3y ago
> 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 https://mermaid.live (linked from https://mermaid.js.org/ 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.
- jillesvangurp 3y ago
  I've used mermaid and lots of other tools. Mermaid is my quick and dirty tool of choice lately, actually. I sank a lot of time in using mermaid to get some sequence diagrams. They suck both visually and the process of creating them is also terrible. But it gets the job done as far as ass-coverage is concerned. The example above tells me that you have a bog standard login thingy that behaves exactly like a login thingy should work (no surprises there). A great way to fluff up some document where you state that your login thingy should be a thing in your thing. Great example of why diagrams are a waste of time. There is zero useful/surprising information in there. Plenty of things I would challenge though. Why does the app have to generate the id for example? What's wrong with the email address as an id? So not only is it uninformative, it's probably wrong.
  - self 3y ago
    > Great example of why diagrams are a waste of time. I need something for the tech people, and I need something for the money people. The diagram gives my target audience (again, non-tech people) an overview of the system. There were sequence diagrams for all the functionality we wrote code for. Technical specs and documentation were also written up, but the money people won't bother to wade through that to understand how it works; the dev team can read that. > Why does the app have to generate the id for example? What's wrong with the email address as an id? The example was extracted from a project I worked on a couple of years ago. I obfuscated what the "id" field is on purpose. If it helps, think of it as the unique device identifier used to send push notifications. > So not only is it uninformative, it's probably wrong. They were not inaccurate.

self 3y ago

> 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 https://mermaid.live (linked from https://mermaid.js.org/ 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.

jillesvangurp 3y ago
I've used mermaid and lots of other tools. Mermaid is my quick and dirty tool of choice lately, actually. I sank a lot of time in using mermaid to get some sequence diagrams. They suck both visually and the process of creating them is also terrible. But it gets the job done as far as ass-coverage is concerned. The example above tells me that you have a bog standard login thingy that behaves exactly like a login thingy should work (no surprises there). A great way to fluff up some document where you state that your login thingy should be a thing in your thing. Great example of why diagrams are a waste of time. There is zero useful/surprising information in there. Plenty of things I would challenge though. Why does the app have to generate the id for example? What's wrong with the email address as an id? So not only is it uninformative, it's probably wrong.
- self 3y ago
  > Great example of why diagrams are a waste of time. I need something for the tech people, and I need something for the money people. The diagram gives my target audience (again, non-tech people) an overview of the system. There were sequence diagrams for all the functionality we wrote code for. Technical specs and documentation were also written up, but the money people won't bother to wade through that to understand how it works; the dev team can read that. > Why does the app have to generate the id for example? What's wrong with the email address as an id? The example was extracted from a project I worked on a couple of years ago. I obfuscated what the "id" field is on purpose. If it helps, think of it as the unique device identifier used to send push notifications. > So not only is it uninformative, it's probably wrong. They were not inaccurate.