I'm creating a sequence diagram for a simple program I'm working on for work. The diagram I'm currently working on is very high level - it defines the interface with lots of alt paths, but does not exemplify any specific use cases. I was wondering whether would it be more appropriate to instead make several diagrams which demonstrate specific examples.
I'm not familiar with the way that these diagrams are intended to be used, and I've seen both specific examples and abstract examples.
Thanks!
Diagrams should help understand things.
If they don't, they fail.
Sequence diagrams are very good at explaining protocols over network and single interactions in a API, in any non-trivial API you're gonna have an hard time describing all interactions. (i.e. you can't)
You obviously have to make multiple diagrams, one for each interaction scenario, making a single diagrams with all the interactions overimposed one another is sick and will make people's eyes cross.
You will still have to write your documentation in natural language, anyway. Diagrams can only help to attain a broader or more precise understanding on top of an already well written documentation.
And if the API implies the usage of different objects, of different classes, by different users, a class diagram, may and will come handy.
It depends entirely on what you want to communicate. In my experience sequence diagrams work great for both very high level through to very low level systems.
For example, we use a sequence diagram showing the event level flow of an SSL handshake to help explain some security related issues to users. Very low level, and very concrete.
We also use a sequence diagram that shows the high level message exchange in our distributed system between the four or five actors in place. That makes each actor something like 50,000 lines of code in size - and events that take multiple communications are one "event" at that scale.
