Formal language for UML sequence diagrams

Question

Is there a formal language which can be used to capture the information present in an UML sequence diagram in to a text format, which is easy understandable by humans?

In our place, often times software requirements are specified in terms of complex sequence diagrams which are difficult to review, verify for correctness and make changes. Also IMHO, programmers would prefer to implement from an unambiguous text representation of the requirements, rather than from sprawling multi page diagrams.

Answer 1

(1) Yes, there is a proprietary almost formal text format language able to express information in UML sequence diagrams understandable by programmers (and may be also by some other humans).

The language I mean was designed and implemented by Steve Hanov, comprehensive list of examples is available at https://www.websequencediagrams.com/examples.html and I have emphasized one of the examples below so that you can get the readability idea:

(2) But, beware that you (or someone else) can write bad, unreadable, code in any language (textual or graphical) and changing the language will not automatically change your (or someone else's) habit's an make the code automatically better, more readable, more maintainable

(2.1) Writing down "unambiguous text representation of the requirements", e.g. in the form of use cases approved by the client is not an easy to-do nor easy to-learn thing and just a language change will not improve it much. (see e.g. Stack Overflow: From user stories to sequence diagram for some more pointers)

(2.2) intended audience (readers) for the UML sequence diagrams are not only programmers but also less technical stakeholders for whom a picture may be worth thousands of words . In my opinion, giving programmers Java pseudo code which can be even reverse-engineered into UML sequence diagram by a tool if needed (see Stack Overflow: how to generate sequence diagram from Java source code or Google: "java sequence diagram" for some more pointers) is better then trying to find/invent a sequence-diagram-specific language

(2.3) there are certainly tools that aid reading large UML designs by using tricks like zooming, hyperlinks, collapsing/expanding blocks, tuning the displayed level of detail and there are paper sizes like A3 or A2 which can turn typical multi-page diagram into single-page diagram

---

From your description it seems that in your place you have process problem and you'd better ask a question at https://softwareengineering.stackexchange.com/help/on-topic

What topics can I ask about here?

Programmers Stack Exchange is a Q&A site for professionals and students in software development and related fields who are interested in getting expert answers on conceptual questions about software development.

If you have a question about...

• software requirements
• software architecture and design
• ...
• development methodologies and processes
• software engineering management
• ...

Answer 2

xmojmr's approach is an effective way of documenting use case scenarios, and if your sequence diagrams are confusing, it's probably because they aren't adequately documented. As xmojmr says, a picture is worth a thousand words, but sometimes a few hundred words really help to explain the picture! I'd like to share a bit of background that you might find helpful.

I see the process of describing requirements as having three levels, of which use case scenarios are the third. Top level is a use case diagram, which shows how the different use cases in a system and the stakeholders using the system interact. Next level is the details of each of those use cases. I use a "use case narrative" for this. Third level is each individual path ("use case scenario") through a use case.

There is a lot of confusion out there between levels two and three. This is partly because to some extent they run together, for example it's reasonable to analyze related success and failure paths through a use case as one scenario rather than two. At least, I prefer to treat them as one scenario.

I prefer to use activity diagrams to document use case narratives. While you can pretty much do anything with a sequence diagram (at least the 2.0 version), IMO divergent behaviors, decision trees, and parallel behaviors are more obvious in activity diagrams than in sequence diagrams. So, one activity diagram per use case, and then one sequence diagram for each separate scenario in the use case.

In your process, it looks like sequence diagrams are not accompanied by formal use case scenario documentation. If you google "use case scenario" you will find a number of examples of such. However, keep in mind that a lot of the examples are actually documenting what I'm calling "narratives".

I'm using the terminology in Tom Pender's The UML Bible (Wiley Publishing, 2003). Another great book is Alistair Cockburn's Writing Effective Use Cases: here is a good-sized sample.

Answer 3

another online text to diagram tool which is using a similar syntax. http://echoma.github.io/text_sequence_diagram/