3 ms·

Some of the resistance I have encountered from developers and engineering managers to writing sequence diagrams has been because it makes it harder for them to

Some of the resistance I have encountered from developers and engineering managers to writing sequence diagrams has been because it makes it harder for them to bullshit about what their code does, how it does it, and how complex (or not) it really is. When you put an abstraction over something its parts can be replacable and in non-growth oriented development cultures this is what people try to avoid. Essentially, resistance to abstraction is often resistance to being managed.

kstrauser 6y ago
More charitably, sometimes it’s impossible to accurately sequence events until you’ve tried implementing a thing, especially so when a 3rd party is involved. We use a vendor’s API that’s very well documented, and if you asked me to chart how we’d use it based on those docs, it would be very straightforward. In reality, we (only halfway) joke that this vendor puts the “eventual” in “eventual consistency”. Like no kidding, it’s often up to 5 minutes between PUTting an object and being able to GET it back. This doesn’t violate any of their API docs at all, but you tend to think of CRUD apps as being either synchronous or having latencies of a second or two. This vendor never claimed to have be that way but I kind of assumed it, which is 100% my fault but still a bit understandable I think. So the actual sequence doc is much more complex with several stages of polling cycles. In fact, it's really a linearization of what's actually implemented as a state machine. If a PM had held me to a simple, linear sequence diagram, they'd be upset that what I delivered didn't look at all like what I'd promised, but that's because we didn't know everything important in advance and we didn't know that we didn't know that. Lessons learned, huh? I don’t mind diagrams for documenting what was actually done so the next maintainer can understand why things are a certain ways. I would enormously resist being made to write code to satisfy them in most contexts.
- hwayne 6y ago
  > We use a vendor’s API that’s very well documented, and if you asked me to chart how we’d use it based on those docs, it would be very straightforward. In reality, we (only halfway) joke that this vendor puts the “eventual” in “eventual consistency”. Like no kidding, it’s often up to 5 minutes between PUTting an object and being able to GET it back. This doesn’t violate any of their API docs at all, but you tend to think of CRUD apps as being either synchronous or having latencies of a second or two. This vendor never claimed to have be that way but I kind of assumed it, which is 100% my fault but still a bit understandable I think. Funnily enough, dealing with a similar vendor is how I got my start with formal methods. Except in addition to 5+ minute latencies, if you sent a second PUT request during that time they _would start randomly deleting data._ Good times, good times.
  - kstrauser 6y ago
    Shudder. This one triggered conversations along the lines of “how hard would it be to replace that vendor with a Django app, really?”
- motohagiography 6y ago
  There are more charitable reasons, I agree. However, the skill of being able to black-box a process is not distributed evenly. "Something goes in, something comes out" is simpler, and yet it requires a mental parallelism that we often don't realize can be more sophisticated than using domain knowledge to serially sound out individual concrete steps and conditions until you find a way to close the conceptual loop. Architects and PM's take flak for not being technical enough because it's generally true that the map is not the territory. But having been there, it can be like watching engineers run a maze without a map, and refusing to either accept a map of the maze, or share a map with anyone else. It's BFS vs. DFS, and they are approapriate for different types of problems. UML in totality is not always helpful, but the most powerful aspects of it can be disruptive to team anti-patterns, and I think this is part of why it has lost a lot of traction.
- cratermoon 6y ago
  > it’s impossible to accurately sequence events until you’ve tried implementing a thing In a general sense it's impossible to accurately model a thing until you've implemented it. All models wrong. Some models are useful. But doing the modelling, in the form of creating a sequence diagram, can be part of the process of going from idea to working code.
whatshisface 6y ago
Managers like knowing what the code will do. The trouble is, compilers also like knowing what the code will do, and as soon as they know, it's time for delivery, and delaying while the boss catches up doesn't seem acceptable. How can managers find out what the code does ahead of delivery? There's only one way: managers have to ask to see the code before the compiler does.

kstrauser 6y ago

More charitably, sometimes it’s impossible to accurately sequence events until you’ve tried implementing a thing, especially so when a 3rd party is involved. We use a vendor’s API that’s very well documented, and if you asked me to chart how we’d use it based on those docs, it would be very straightforward. In reality, we (only halfway) joke that this vendor puts the “eventual” in “eventual consistency”. Like no kidding, it’s often up to 5 minutes between PUTting an object and being able to GET it back. This doesn’t violate any of their API docs at all, but you tend to think of CRUD apps as being either synchronous or having latencies of a second or two. This vendor never claimed to have be that way but I kind of assumed it, which is 100% my fault but still a bit understandable I think. So the actual sequence doc is much more complex with several stages of polling cycles. In fact, it's really a linearization of what's actually implemented as a state machine. If a PM had held me to a simple, linear sequence diagram, they'd be upset that what I delivered didn't look at all like what I'd promised, but that's because we didn't know everything important in advance and we didn't know that we didn't know that. Lessons learned, huh? I don’t mind diagrams for documenting what was actually done so the next maintainer can understand why things are a certain ways. I would enormously resist being made to write code to satisfy them in most contexts.

hwayne 6y ago
> We use a vendor’s API that’s very well documented, and if you asked me to chart how we’d use it based on those docs, it would be very straightforward. In reality, we (only halfway) joke that this vendor puts the “eventual” in “eventual consistency”. Like no kidding, it’s often up to 5 minutes between PUTting an object and being able to GET it back. This doesn’t violate any of their API docs at all, but you tend to think of CRUD apps as being either synchronous or having latencies of a second or two. This vendor never claimed to have be that way but I kind of assumed it, which is 100% my fault but still a bit understandable I think. Funnily enough, dealing with a similar vendor is how I got my start with formal methods. Except in addition to 5+ minute latencies, if you sent a second PUT request during that time they _would start randomly deleting data._ Good times, good times.
- kstrauser 6y ago
  Shudder. This one triggered conversations along the lines of “how hard would it be to replace that vendor with a Django app, really?”
motohagiography 6y ago
There are more charitable reasons, I agree. However, the skill of being able to black-box a process is not distributed evenly. "Something goes in, something comes out" is simpler, and yet it requires a mental parallelism that we often don't realize can be more sophisticated than using domain knowledge to serially sound out individual concrete steps and conditions until you find a way to close the conceptual loop. Architects and PM's take flak for not being technical enough because it's generally true that the map is not the territory. But having been there, it can be like watching engineers run a maze without a map, and refusing to either accept a map of the maze, or share a map with anyone else. It's BFS vs. DFS, and they are approapriate for different types of problems. UML in totality is not always helpful, but the most powerful aspects of it can be disruptive to team anti-patterns, and I think this is part of why it has lost a lot of traction.
cratermoon 6y ago
> it’s impossible to accurately sequence events until you’ve tried implementing a thing In a general sense it's impossible to accurately model a thing until you've implemented it. All models wrong. Some models are useful. But doing the modelling, in the form of creating a sequence diagram, can be part of the process of going from idea to working code.

whatshisface 6y ago

Managers like knowing what the code will do. The trouble is, compilers also like knowing what the code will do, and as soon as they know, it's time for delivery, and delaying while the boss catches up doesn't seem acceptable. How can managers find out what the code does ahead of delivery? There's only one way: managers have to ask to see the code before the compiler does.