What is a Good Textual Representation of Activity Diagrams in Requirements Documents?

Abstract

Abstract-The use of graphical models has become a widely adopted approach to specify requirements of complex systems. Still, in practice, graphical models are often accompanied by textual descriptions to provide more detail, because of legal considerations, and to enable stakeholders with different backgrounds to understand a requirements document. One of our industry partners (Daimler AG) uses activity diagrams to specify vehicle functions in combination with a textual representation thereof in their requirements documents. Since graphical and textual representations serve different purposes, it is not obvious how textual representations of activity diagrams should be structured. In this paper, we present different textual representations of activity diagrams for use in requirements documents. The representation currently in use is presented as well as four alternatives. For each representation, we discuss advantages and disadvantages. To evaluate the representations, we asked five stakeholders of one system to create a preference ranking of the representations. The resulting ranking showed that the currently used representation is not considered to be the best possible option. The stakeholders' favorite textual representation emphasizes structural similarity with the activity diagram, which however does not resemble the diagram's structure exactly.

Coexisting Graphical and Structured Textual Representations of Requirements: Insights and Suggestions

“…The coexistence of textual descriptions and graphical models appears to be a possible solution to this issue [23]. Nevertheless, there might be more fitting possibilities to arrange the textual representation than the one currently used (see [24] for a study on different textual representations of activity diagrams).…”

Removal of Redundant Elements within UML Activity Diagrams

“…Nonetheless, existing redundant elements complicate possible approaches of automation. For instance, in requirements engineering activities need to be accompanied by textual representations [9]. As a result, a well-structured requirements document should reflect, which executions are possible and necessary in an activity.…”