I've been asked to make a sequence diagram to document the web service calls made by my application.
I don't really understand sequence diagrams. They're difficult to read – lots of lines, not a lot of text. For example, if I want to show that my app makes a call to a specific service, passing a set of data and getting back a different set of data, there's hardly enough room on the line out and the line back to show all this data and to point out that it's a GET or a POST, and without this information, the diagram is minimalistic to the point of not being very useful. I find it a lot easier to document stuff like this in a text file or on a wiki. But I see how popular sequence diagrams are, so I think I'm not 'getting' them.
So I have three questions right now:
(1) Can someone show me some particularly good/useful examples of a sequence diagram for web service calls, so I can see how this is done right?
(2) When a flow has different logic paths that result in different web service calls, should I represent these by if/then/else in a single sequence diagram, or create a different sequence diagram for each possibility?
(3) I understand that sequence diagrams are based on UML, but in what way is UML a "language"? There's no text representation of it, right? It seems more a way of diagramming something, like a flowchart.
Best Answer
The purpose of the sequence diagram in your case is communicating certain information to your colleagues (or future self). There really is no "best" way how to go about it, just like there isn't a best way to write this answer -- I've already reworded this answer, and if I were to re-read my answer in a year, I would probably reword it again to be more clear.
The very same goes for diagrams here; if you don't understand the diagram yourself (assuming you understand the purpose of sequence diagrams), then other people are not going to understand it either.
Maybe in your case something like this could suffice
Focus on communication first, worry about being "compliant" to UML specs later.
(3) Would you consider sign language a language even though it uses hand gestures instead of text?
Similarly UML has a "vocabulary" of visual elements that represent various concepts --- sequence diagrams with their lifelines and messages express a sequence of communication between actors (classes). Also, you can add notes to your diagram to clarify your intent.
(2) You can do both. Again, the deciding factor is clarity of communication -- if a single diagram is a too cluttered then break it up and make another one, or dozen more (just like you would split up methods, and classes). A rule of thumb is to keep the same level of abstraction in the whole diagram -- suddenly diving into implementational details can clutter it very quickly.
(1) The best way to start is to first learn the "vocabulary" of the diagrams e.g. uml-diagrams.org, then draw something and see if you understand it or if other people understand it; don't be afraid to throw a diagram away if you feel you can "reword" it better.
sounds like a tooling problem; just put the lines further apart, or use things like PlantUML that does that for you. (Or use an actual UML tool.)
Then enrich it, add text annotation, split it up. Use it as part of documentation to illustrate only certain points; you don't have to use the diagram as the only documentation artifact.