Modeling state transitions used to be big important step of software design. UML has specialized diagrams dedicated for that. The problem with these diagrams is that they get outdated as soon as you start coding and the job of repeatedly fixing your diagrams to reflect what your code does means that this never happens and the diagrams get outdated very quickly.
Agile/extreme programming pretty much put a stop to writing documentation like this. These days few programmers even know what UML is and most have never encountered it professionally. I think that is a positive change. Build code, not stupid slide ware.
The reason for this is that this type of documentation is very maintenance heavy and only makes sense in waterfall style processes, which you should not be doing at this point. It got replaced by people drawing on whiteboards and maybe taking a photo of it. The value beyond the relevant sprint, or meeting, is usually very limited. They are great during meetings and their value drops rapidly after that meeting concludes. I've been in meetings where people take photos of whiteboards. In my view, even that is a waste of time. Just wipe it and move on.
A big problem is that state diagrams (and other diagrams) tend to abstract away too much information. A state diagram with around five states makes great slide-ware. But if your implementation has 25 states and dozens of arrows, that same slide basically becomes a mess and a PITA to update. So diagrams are great for things that are easy to explain without diagrams and not so great for more complicated things. In practice, if you can easily draw diagram, it's probably not worth bothering and if you can't you might consider writing a prototype instead.
Real systems tend to be more complicated than what you can fit in a diagram. Ultimately, it is the more complicated systems where people desire documentation; not the super simplistic systems where the documentation just states the bleedingly obvious. This is the reason UML died. It was used exclusively to document completely obvious things as part of rather pointless documentation that typically only told half the story. At great cost even.
I've seen and contributed to a fair bit of so-called architecture documents. This was a rather pointless artifact that used to be a box ticking exercise that involved a lot of tooling for drawing pretty pictures. Thankfully, it's been a while since I've been in a project where people asked for this. I used to refer to this as write only documentation because nobody actually reads this stuff. Project bureaucracy like this needs to be kept to a minimum.
I always joked that all the nice OSS UML tooling out there came without UML documentation. They did not eat their own dog food. None of them. UML documentation for OSS projects was never a thing. Even for OSS software intended to support writing UML diagrams.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Modeling state transitions used to be big important step of software design. UML has specialized diagrams dedicated for that. The problem with these diagrams is that they get outdated as soon as you start coding and the job of repeatedly fixing your diagrams to reflect what your code does means that this never happens and the diagrams get outdated very quickly.
Agile/extreme programming pretty much put a stop to writing documentation like this. These days few programmers even know what UML is and most have never encountered it professionally. I think that is a positive change. Build code, not stupid slide ware.
The reason for this is that this type of documentation is very maintenance heavy and only makes sense in waterfall style processes, which you should not be doing at this point. It got replaced by people drawing on whiteboards and maybe taking a photo of it. The value beyond the relevant sprint, or meeting, is usually very limited. They are great during meetings and their value drops rapidly after that meeting concludes. I've been in meetings where people take photos of whiteboards. In my view, even that is a waste of time. Just wipe it and move on.
A big problem is that state diagrams (and other diagrams) tend to abstract away too much information. A state diagram with around five states makes great slide-ware. But if your implementation has 25 states and dozens of arrows, that same slide basically becomes a mess and a PITA to update. So diagrams are great for things that are easy to explain without diagrams and not so great for more complicated things. In practice, if you can easily draw diagram, it's probably not worth bothering and if you can't you might consider writing a prototype instead.
Real systems tend to be more complicated than what you can fit in a diagram. Ultimately, it is the more complicated systems where people desire documentation; not the super simplistic systems where the documentation just states the bleedingly obvious. This is the reason UML died. It was used exclusively to document completely obvious things as part of rather pointless documentation that typically only told half the story. At great cost even.
I've seen and contributed to a fair bit of so-called architecture documents. This was a rather pointless artifact that used to be a box ticking exercise that involved a lot of tooling for drawing pretty pictures. Thankfully, it's been a while since I've been in a project where people asked for this. I used to refer to this as write only documentation because nobody actually reads this stuff. Project bureaucracy like this needs to be kept to a minimum.
I always joked that all the nice OSS UML tooling out there came without UML documentation. They did not eat their own dog food. None of them. UML documentation for OSS projects was never a thing. Even for OSS software intended to support writing UML diagrams.