Masarykova univerzita
Fakulta informatiky
UML modeling tools for blind people
Bakalářská práce ukáš Tyrychtr 2017
Prohlašuji, že tato práce je mým původním autorským dílem, které jsem vypracoval(a) samostatně. Všechny zdroje, prameny a literaturu, které jsem při vypracování používal(a) nebo z nich čerpal(a), v práci řádně cituji s uvedením úplného odkazu na příslušný zdroj.
Tato práce se zabývá nástroji použitelnými nevidomými při tvorbě a procházení již existujících UML diagramů.
Práce shrnuje stav použitelných nejen softwarových nástrojů použitelných při prezentaci UML diagramů, a rovněž představuje výsledky studie použitelnosti PlantUML.
Klíčová slova: UML, nástroje, nevidomí, přístupnost, PlantUML Table of contents Table of contents ...... 4 Introduction ...... 5 About UML ...... 5 Current tools and state of the research ...... 6 UML diagram presentation approaches ...... 6 Software tools ...... 6 PlantUML ...... 12 Syntax ...... 12 The syntax choices ...... 30 PlantUML and visually impaired users ...... 30 The questions ...... 30 The subjects ...... 31 The questioning ...... 31 The questions and their answers ...... 31 Visual aspects of the PlantUML output ...... 43 Conclusions ...... 44 Appendix ...... 45 PlantUML Installation note ...... 45 Resources ...... 46
4
Introduction Despite UML being so ubiquitous in the software engineering community, not much research has gone towards finding how a blind user can cooperate with his colleagues. This work thus wants to present the current available tools and then assess in more detail the usability of PlantUML in cooperation between blind users and their colleagues while understanding a moderately complex diagram and suggest possible improvements to make the cooperation more streamlined. Such improvements may include suggestions for syntax changes, diagram organization guidelines and other suggestions.
This work first explains the current state of this area – presentation approaches, current software tools and it also presents a quick PlantUML syntax refresher.
The second major part presents the results of a survey of PlantUML users, particularly visually impaired ones, but the visual presentation is also looked at briefly.
About UML "The Unified Modeling Language (UML) is a general-purpose visual modeling language that is used to specify, visualize, construct, and document the artifacts of a software system. It captures decisions and understanding about systems that must be constructed. It is used to understand, design, browse, configure, maintain, and control information about such systems." (1)
It was created to centralize the various existing representations and in 2005 it was accepted as a ISO standard (2). UML defines a few visualization types, some are used more than others.
Before continuing with a more thorough exploration of the software aspect of UML, the following paragraphs briefly describe the diagram types defined by the UML specification.
The use case diagram describes on a high level the usage scenarios of a software system and their actors. It can help making sense of the required entities and the functionality needed.
The sequence diagram describes a set of sequential steps of a process by showing the individual interactions. It is not usually created for each part of the system, but it can help in more complex cases.
The communication diagram is like the sequence diagram, but it focuses more on the passed messages. It is possible to express a communication flow by both diagram types.
The communication overview diagram also shows some business process, but on a higher level of interaction. Instead of individual steps it shows individual interaction diagrams (activity, sequence etc.).
The timing diagram shows a sequence of events roughly as a sequence diagram, but when more objects are involved it helps to highlight the timing relations.
In an activity diagram you usually display a part of a functionality in more detail including all the conditions, loops and other flow control elements, but you do not perform this for each function.
5
A state diagram represents the possible states and their transitions in a part of a system or some of its objects. As such, it is also known as the state machine diagram.
A class diagram depicts the overall class hierarchy and the relationships within it. It might be more detailed including class attributes and methods, but this detailed analysis is usually done only in a later planning stage and maybe not for all classes. It is one of the most common diagram types used.
An object diagram is somewhat like a class diagram, so it also shows class relations, but in this case concrete instances of the classes are used. It can help in understanding some more complex data relationships.
A component diagram shows the relationships between larger system components (databases, application servers etc.) and the interfaces used.
In a deployment diagram the relationships and aspects of the hardware of the system are shown. It is used when the software system requires a multi-machine setup with the hardware nodes being different in some way.
The package diagram is used to show the application namespace structure and the imports between the individual packages.
The composite structure diagram is used to show the composite structure of a class.
The profile diagram was added in the UML 2.0 specification. It is used to customize the UML metamodels somewhat, for example to allow only single inheritance.
It mainly consists of stereotypes, tagged values and constraints.
Current tools and state of the research
UML diagram presentation approaches When it comes to presenting the UML diagram to a visually impaired user, there are basically two options.
First, a tactile image is used (3). This approach is sensitive to the diagram complexity, because the result can quickly get incomprehensible for the visually impaired reader. And it takes somewhat longer to create. Those diagrams may be created by hand, or a braille embosser can be used.
On the other hand, a properly selected software tool can support both visual and accessible representation, thus making the communication much easier.
Software tools There are basically three categories of tools used. The first category is probably the most numerous containing all the software which all the other (e. g. developers with sight) use. One of them, if written well, could integrate some sort of accessibility support.
The second class is a specialized application which allows the user to have some spoken representation of the diagram, while also displaying it visually. This category of tools is rare, and the results of development have not been promising so far. The European Union started a project in this category of development in 2001 (4), but its results were evaluated as a failure and the project was
6 stopped in 2005. It has managed to produce a viewer application, called Accessible UML, which supports viewing of class, sequence and use case diagrams both as a list of elements with some additional information (connections, attributes etc.), and as a graphical view. However, the application does not support creating and editing operations.
The other category of tools uses textual input and produces an image of the resulting diagram.
The category of textual UML tools is numerous, as can be seen from the list at (5). However, not many tools support more than a few diagram types, most common is support for class and sequence diagrams.
Here, I will only briefly talk about some of the more promising tools from the point of view of the visually impaired UML creator and then continue with more in-depth analysis of PlantUML (6), because as the next chapters show, it is one of the most promising tools.
Standard tools In this, part of the thesis I will briefly look at the accessibility potential of the more popular general UML tools.
The testing was done on Windows 10 with the latest NVDA screen reader version (7).
ArgoUML ArgoUML (8) is one of the few open-source visual UML tools. Testing the latest version (0.34) showed that the interface in general (controls for creating a diagram etc.) were accessible, but the crucial user interface control, the diagram area, was not.
Enterprise architect The testing of an Enterprise architect 13.5 trial (9) showed basically the same results as ArgoUML. The menus worked fine, but there was no accessibility support for the diagram area.
IBM tools The situation of IBM Rational rhapsody (10) and IBM rational software architect designer (11) was the same as for the other tested tools.
MetaUML MetaUML (12) is an application which supports creating a visual representation of package, class, activity, use case, component and state machine diagram given its textual representation. The syntax is however not ideal for the use case of writing the diagrams by hand by a blind user, because it requires a lot of visual appearance control commands. For reference see for example the activity diagram at (13), whose code follows for convenience.
Begin.b;
Activity.eat("Eat something good", "from the kitchen");
Branch.enough;
Fork.fork("h", 50);
Activity.read("Read a book");
7
Activity.listen("Listen to music", "(and ignore it)");
Fork.join("h", 50);
End.e;
leftToRight.top(10)(read, listen);
Group.readListen(read, listen);
leftToRight(30)(b, eat); topToBottom(20)(eat, enough, fork, readListen, join, e);
drawObjects(b, eat, enough, fork, readListen, join, e);
clink(transition)(b, eat); clink(transition)(eat, enough); link(transition)(pathStepX(enough.e, eat.e, 80)); clink(transition)(enough, fork); clink(transition)(fork, read); clink(transition)(fork, listen); clink(transition)(read, join); clink(transition)(listen, join); clink(transition)(join, e);
item(iGuard)("still hungry")(obj.sw = enough.e + (20, 0)); item(iGuard)("had enough")(obj.nw = enough.s + (0, -4));
This diagram is represented by figure 1.
8
Figure 1 - Example of a MetaUML diagram
Graphviz Graphviz (14) is a general graph visualization tool, which can be used to draw graph-like structure, including the software engineering diagrams. This flexibility comes at a cost, however. The textual input does not survey any semantical meaning, the definition is on the level of graph nodes, arrows, colours etc.
This level of abstraction is however quite suitable as an intermediate diagram representation, because the higher-level tool (e. g. PlantUML) does not have to handle the graph drawing itself. But just to demonstrate, the following is an example of a simple class diagram using Graphviz syntax: digraph Couriers { node [shape = "record"] edge [arrowtail = "empty"]
Courier [label = "{Courier|+ name : string\l+ home_country : string\l|+ calculateShipping() : float\l+ ship(): boolean\l}"]
Monotype [label = "{MonotypeDelivery|\l|+ ship(): boolean\l}"]
Pigeon [label = "{PigeonPost|\l|+ ship(): boolean\l}"]
Courier -> Pigeon [dir=back]
Courier -> Monotype [dir=back]
}
This simple example renders as can be seen in figure 2.
9
Figure 2 - Example of a Graphviz diagram
As can be seen from the Graphviz syntax example above, for general graph drawing, the syntax is adequate, but note for example the absence of class method representation syntax.
SVG SVG (15) is a general vector graphic description language, so in theory it should be possible to write diagrams directly in that format, but the level of abstraction of the format is much lower for this particular use case. Just as an example, the first PlantUML activity diagram example presented below would be in SVG written as (direct output from PlantUML):
10
And is displayed as figure 3 shows.
Figure 3 - Example of a diagram written in svg
Of course, if we would like to get simpler, some colour control could probably be omitted, but the layer of abstraction would stay the same nonetheless.
11
PlantUML PlantUML (6) is a java based tool which can generate images of sequence, use case, class, activity, component, state, deployment and object diagrams. The application supports PNG, SVG and LaTeX as its output format. Installation is not necessary, it is possible to use the Online demo server. The output is quite understandable, and it is possible to fine tune the graphical output if needed, which of course requires a sighted help or some previous experience.
Syntax Every PlantUML diagram is delimited by the @startuml and @enduml keywords. Not including this, the syntax is specific for each diagram type.
This section is not a definitive syntax/feature guide, for all the relevant information please see the relevant resources.
Sequence diagrams A basic sequence diagram would be written as:
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
Alice and Bob are the actors of the diagram. Note that they do not need to be previously declared. The -> and <-- symbols signify the arrows. The number of dashes does not alter the visual appearance.
This short example results in figure 4.
Figure 4 - Simple sequence diagram
You can also define actors before they appear, which looks as:
12
@startuml actor Foo1 boundary Foo2 control Foo3 entity Foo4 database Foo5
Foo1 -> Foo2 : To boundary
Foo1 -> Foo3 : To control
Foo1 -> Foo4 : To entity
Foo1 -> Foo5 : To database
@enduml
There are five kinds of actors: actor, boundary, control, entity and database. The differences of them are mainly in the display. Figure 5 shows them:
Figure 5 - Example of the various sequence diagram actor types
It is also possible to rename the actors using the as keyword:
@startuml actor Alice as A actor Bob as B
A -> B: Authentication Request
13
B --> A: Authentication Response
A -> B: Another authentication Request
A <-- B: another authentication Response
@enduml
And it displays as is shown in figure 6.
Figure 6 - Example of an sequence diagram with renamed actors
A message with the same participant on both sides is also valid:
@startuml
Alice->Alice: This is a signal to self
@enduml
And it looks as is shown in figure 7.
Figure 7 - sequence diagram with self message
Some other features are also available, such as changing the arrow style, adding notes etc.
The rest is described in (16).
14
Use case diagrams The individual use cases are defined as:
@startuml
(First usecase)
(Another usecase) as (UC2) usecase UC3 usecase (Last\nusecase) as UC4
@enduml
There are two ways how to declare use cases: by enclosing them in ( and ), or by the usecase keyword. In both cases you can rename them using the as keyword.
This simple example results in figure 8.
Figure 8 - Simple use case diagram
The situation with actor definition is somewhat similar:
@startuml
:First Actor:
:Another\nactor: as Men2 actor Men3 actor :Last actor: as Men4
@enduml
They can be defined either by enclosing them between :, or it is possible to use the actor keyword.
And they look like as figure 9 shows.
15
Figure 9 - Use case diagram with actors
The linking is done using arrows:
@startuml
User -> (Start)
User --> (Use the application) : A small label
:Main Admin: ---> (Use the application) : This is\nyet another\nlabel
@enduml
The number of dashes affects the arrow length. As you can see from this example, declaration is not required.
The visual result is shown by figure 10.
16
Figure 10 - Use case diagram with links
It is possible to declare extension of actor/use cases using the <|-- symbol:
@startuml
:Main Admin: as Admin
(Use the application) as (Use)
User <|-- Admin
(Start) <|-- (Use)
@enduml
The visual result looks like figure 11.
17
Figure 11 - Use case actor extension
Some other features include adding notes, visual style adjustment etc. The complete definition of the syntax is at (17).
Class diagrams First off, the relationships between classes are defined as:
@startuml
Class01 <|-- Class02
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 -- Class10
@enduml
Where <|-- is extension, *-- is composition and o-- is aggregation. It is also possible to create a dotted line by using ..
Those relations are displayed as is shown in figure 12.
Figure 12 - Class relations
Labels on relations are added after a : following the relation. Cardinality is denoted on the respective sides of the relation symbol:
18
@startuml
Class01 "1" *-- "many" Class02 : contains
Class03 o-- Class04 : aggregation
Class05 --> "1" Class06
@enduml
This usage displays as is shown by figure 13.
Figure 13 - Class relations with labels and cardinality
There are two possibilities how to declare fields and methods. The first uses : after the class name as such:
@startuml
Object <|-- ArrayList
Object : equals()
ArrayList : Object[] elementData
ArrayList : size()
@enduml
It displays as is shown by figure 14.
19
Figure 14 - Class fields
The second approach uses brackets:
@startuml class Dummy {
String data
void methods()
}
class Flight {
flightNumber : Integer
departureTime : Date
}
@enduml
Both type declaration styles are possible.
This class diagram displays as is shown by figure 15.
Figure 15 - Class fields, curly brackets form
Visibility is controlled using a character before the method/field name where means private, # means protected, ~ means package private and + means public. The display is showcased by the following diagram:
@startuml
20 class Dummy {
-private
#protected
~packagePrivate()
+public()
}
@enduml
And the visual output is equal to figure 16.
Figure 16 - Class field visibility
Static and abstract fields also work:
@startuml class Dummy {
{static} String id
{abstract} void methods()
}
@enduml
Those elements display as figure 17 shows.
Figure 17 - Abstract and static class fields
Usage of abstract classes and interfaces is also possible:
@startuml
abstract class AbstractList abstract AbstractCollection
21 interface List interface Collection
List <|-- AbstractList
Collection <|-- AbstractCollection
Collection <|- List
AbstractCollection <|- AbstractList
AbstractList <|-- ArrayList
class ArrayList {
Object[] elementData
size()
}
enum TimeUnit {
DAYS
HOURS
MINUTES
}
annotation SuppressWarnings
@enduml
The previous example also shows usage of enumerations and annotation definitions and renders as is shown in figure 18.
22
Figure 18 - Abstract classes, interfaces, enumerations and annotations
Some other less often used features of the class syntax also exist, the complete reference is at (18).
Activity diagrams PlantUML has two syntax flavors for the activity diagram. This section will only describe the new syntax.
A basic diagram looks like:
@startuml
:Hello world;
:This is defined on several lines;
@enduml
Activities are linked automatically, and multiline activity descriptions are available thanks to the label delimiters.
This diagram's visual form is shown in figure 19.
Figure 19 - Basic activity diagram
23
You can explicitly add the start and stop keywords to denote start and end of the activity diagram respectively.
Conditionals are represented using if/elseif/else blocks and the entire construct is closed by an endif as is shown in the following example:
@startuml start if (condition A) then (yes)
:Text 1; elseif (condition B) then (yes)
:Text 2;
stop elseif (condition C) then (yes)
:Text 3; elseif (condition D) then (yes)
:Text 4; else (nothing)
:Text else; endif stop
@enduml
Those syntactic elements display as figure 20 shows.
24
Figure 20 - Activity diagram with conditionals and explicit start and stop markers
A do while loop is written as:
@startuml start repeat
:read data;
:generate diagrams; repeat while (more data?) stop
@enduml
And is shown in figure 21.
Figure 21 - Activity diagram with a do while loop
25
And a while loop can be represented as:
@startuml start while (data available?)
:read data;
:generate diagrams; endwhile stop
@enduml
And the rendering is shown in figure 22.
Figure 22 - Activity diagram with a while loop
Some other features regarding parallelism and visual parameters exist, they are described at (19).
Component diagrams A basic component diagram in the PlantUML syntax is written as:
@startuml
DataAccess - [First Component]
[First Component] ..> HTTP : use
@enduml
The bracketed identifiers denote components. It would be possible to define them beforehand using the component keyword. Interfaces do not have to be defined, but a definition may be done using the interface keyword or by using () before the interface identifier.
This simple case of a component diagram renders as is shown by figure 23.
26
Figure 23 - Simple component diagram
Grouping is also available using a few flavors:
@startuml package "Some Group" {
HTTP - [First Component]
[Another Component]
}
node "Other Groups" {
FTP - [Second Component]
[First Component] --> FTP
}
cloud {
[Example 1]
}
database "MySQL" {
folder "This is my folder" {
[Folder 3]
}
frame "Foo" {
27
[Frame 4]
}
}
[Another Component] --> [Example 1]
[Example 1] --> [Folder 3]
[Folder 3] --> [Frame 4]
@enduml
This case displays as is shown in figure 24.
Figure 24 - Component diagram with the various grouping constructs
28
Other features like notes and visual control also exist, see (20) for more details.
State diagrams A simple state diagram is written as:
@startuml
[*] --> State1
State1 --> [*]
State1 : this is a string
State1 : this is another string
State1 -> State2
State2 --> [*]
@enduml
The [*] symbol denotes the starting and stopping state and -> denote the transitions.
This diagram is graphically represented by figure 25.
Figure 25 - Simple state diagram
It is possible to create a composite state using a state block as:
@startuml state NotShooting {
[*] --> Idle
Idle --> Configuring : EvConfig
Configuring --> Idle : EvConfig
}
@enduml
29
And renders as is shown by figure 26.
Figure 26 - State diagram with composite state
Some color control, notes and other features are available, see (21) for the complete reference.
Other diagram types Not including the diagram types listed above, PlantUML supports object, timing and deployment diagrams from the UML diagram family and a few other types which are not relevant for this work.
The object diagram syntax is somewhat like the class diagram one, albeit with fewer features. Deployment diagrams have object types like the package diagram and a lot of arrow types which are not semantically described in the reference.
Timing diagrams could have some value, but they were not as deeply explored in the university course, so they will not be the main objective for this thesis.
The syntax choices As is obvious from the preceding sections, in many cases there are more ways of representing a syntactic element.
Despite the approaches being semantically equivalent, it might be possible that for understanding by visually impaired people they are not the same.
PlantUML and visually impaired users In this chapter the results of the study between visually impaired users of PlantUML are presented.
First, a general overview of the questions is presented.
In the following sections the respondents and the study approaches are presented.
The last section presents results of the research.
The questions There are basically two broad types of questions which can be asked about each of the PlantUML diagram types. The first is concerned with the best practices of using the currently available features.
30
Those questions often try to determine the more accessible syntax form of a diagram construct, for example whether both arrow directions should be used or whether it is better to swap the linked entities.
The second kind of questions are basically syntax change suggestions. The reason for those is that for example, class inheritance could be stated in the class header. More details about the questions and the answers will be presented in a later chapter.
The subjects Unfortunately, the requirements of participants are quite specific. Firstly, it is helpful if they are visually impaired, so they would have at least a chance of using the examined tools. And to make things more complicated, the at least possible usage requirement limits the users to information technology university students or people working in a company with at least moderate UML usage.
Despite those constraints, there are at least two approaches of getting in touch with the people. The first is through university centers for students with disabilities. The second source are mailing lists and forums for visually impaired programmers.
Universities For the university student group only Czech universities were selected, because one of the first stages of the research planning included an in-person meeting.
Further research with help of the relevant centers for students with disabilities showed that on Masaryk university only 6 students met the conditions listed above and on the Olomouc university only one student was found.
International programming groups Because of the university students count the Program-l mailing list (22) was chosen as an additional source of visually impaired UML users.
This list has members of all programming education styles from hobbyists to university students, so from the 495 members in total and the 244 active members (because they sent at least one post) it was not clear how many fit the requirements exactly.
The questioning Despite a in person meeting being superior to the chosen answer retrieval method, the geographical diversity and generally complex time constraints prevented even a video conference from happening. To at least retrieve some data, two Google forms were created. The questions of the two forms were identical, they only differed in the language used.
The forms were posted around April 2017 along with the survey announcements. The exact timing of the messages to the university students is not known, because those e-mails were sent by the centers because of privacy and other reasons. The results were looked at periodically, but lastly at 11th November 2017.
The questions and their answers In the survey, there were a few general question types. One of them was a general part about the participant and then the diagram type specific sections followed.
31
Out of the 7 university students, only one answered. Because of the survey's anonymity, it could have been someone from Masaryk university and from the same subject which was the inspiration of this work, but it is not certain.
The users of the mailing list were a little bit numerous, 18 of them answered.
So, to summarize, there was 19 answers in total.
The general questions Before delving into the details of UML and PlantUML, some general data was obtained about the respondents.
The questioning used the following questions:
Question: You work with UML
Choices: daily, once in a week, less often
Question: Where do you / did you work with UML
Choices: At work, In a university course, Because of some hobby projects
Question: What's your opinion about UML?
Choices: It's a useful tool, It is a useful tool, but the graphical nature limits the usefulness for visually impaired people, It might be a useful tool, It is not a useful tool
All the 19 participants met with UML at a university course and work with it less often than once in a week.
When asked about the usefulness of UML, one replied that it is a useful tool, the rest concluded that it might be useful, but the graphical nature limits the usefulness.
Encountered UML Tools This section was about determining what other tools were encountered by the respondents.
It consisted of the following questions:
Question: Which UML tools have you encountered?
Choices: MetaUML, PlantUML, Other
Question: If you want, you can express your opinions about some of the UML tools. Note that PlantUML will be surveyed in more detail later.
Choices: open question with a text area
When it came to the tools, all the respondents met with PlantUML and one with MetaUML, but he did not provide any experiences related to this tool. No other tools were mentioned in the open question either.
32
Sequence diagrams This section of the survey explored the syntax and other aspects of the sequence diagram syntax.
The declaration of entities The purpose of this question was to determine whether the declaration of entities is worthwhile.
The question had the following introductory text:
Let's have the following, semantically equal, diagrams:
@startuml
Client -> Server: Send version
Server -> Db: Check Ip ban
Server -> Client: Send response
@enduml and
@startuml actor Client actor Server actor Db
Client -> Server: Send version
Server -> Db: Check Ip ban
Server -> Client: Send response
@enduml
Question: Which of the following diagrams looked more obvious?
Choices: Diagram one, Diagram two, It is basically the same
When asked about whether it is useful to define the actors before use, the participants did not come to a conclusive answer. All the possible answers – yes, no and does not matter much occurred roughly the same number of times. 6 answers marked as the more useful diagram form the one without declaration, 6 participants preferred the declaration and 7 did not see a difference.
Because the definite answers occurred exactly six times each, it is not possible to draw any conclusions from the answers except perhaps that on such a small scale of a diagram there is not much of a difference.
Arrow directionality This question wanted to determine whether the directionality of PlantUML arrows was useful or not.
33
It had the following introductory text:
The following diagrams are different only in the detail how the arrows are used:
@startuml
Client -> Server: Send version
Server -> Db: Check Ip ban
Server -> Client: Send response
@enduml
We can write the same as:
@startuml
Client -> Server: Send version
Db <- Server: Check Ip ban
Client <- Server: Send response
@enduml
Question: Which version is clearer?
Choices: 1. Version, 2. Version, It's not so important
Question: If you want, you can explain your answer to the question above.
Choices: open question with a text field
Answers:
1. it's easier to follow classic left to right relations
2. it's somewhat easier to follow left to right relations
Somewhat surprisingly, given two diagrams differing only by the way how arrows were used, the participants preferred differing arrow directions, e. g. preferred version 2.
13 users preferred directional arrows, 6 did not and nobody marked the does not matter choice.
The respondents which chose the version with differing arrow directions did not provide any explanation why they did so, the few explanations of the reason for the unidirectional version boiled down to the fact that it is easier to follow left to right relations. Only two of the supporters of the first style provided an answer why they did so, see the answers section of the last question in this subsection for the exact wording.
In this case, it is quite clear that directional arrows should be used whenever they appear in a diagram.
34
Overall sequence diagram syntax The questions did not touch on all aspects of the syntax, so perhaps someone wanted to explain himself more.
Question: If you have any other ideas how to improve the sequence diagram syntax, tell me.
Choices: open question
Answers:
1. This is not really related to the syntax, but I think it could be useful. Some kind of plant uml IDE, which would automatically check syntax and warn you if you made an error. Also, a way to check if you made the diagram correctly, a tree view or something which would show all the entities and their relations.
One person provided an answer. The respondent used the area for a suggestion for some sort of a PlantUML integrated development environment (exact words are in the first answer of the last question of this subsection), which in its own right is a useful input, however it was not relevant for the specific question.
Use case diagrams In this part of the survey the respondents were asked some questions about use case diagrams.
Keyword versus braces The PlantUML syntax allows to use the usecase keyword, but it does not require it. So, the question is whether visually impaired users have an opinion.
The question introductory text was:
The diagrams below are semantically the same thing:
@startuml
(First usecase)
(Another usecase) as (UC2)
@enduml and
@startuml usecase (First usecase) usecase (Another usecase) as (UC2)
@enduml
Question: Which of the styles looks clearer to you?
Choices: The first, The second, In this case it is somewhat the same
35
Question: In a bigger diagram, would it be better to use the keywords, or parentheses?
Choices: Definitely the keywords, Definitely the parentheses, It would be the same
When it comes to the question whether to use a keyword or a brace, the answer is definite, use the keyword, only one response favored the usage of the brace syntax and no answer chose the does not matter there answer.
When the respondents were asked whether in a bigger diagram the keyword would be preferred, all 19 answered that yes, it would.
From this it is clear that using the keyword form is preferred.
Actor declaration This is another instance of the declaration before use or not question. Both syntax forms are possible, however in the previous cases where such a choice existed there was often a preference for one of the styles. This question tries to find out whether the preference exists also in this case.
Question: We already saw a declaration before first use. Do you think that the actors should also be declared first?
Choices: Definitely, Depends on the diagram size, Doesn't have to
Most of the respondents think that declaring use case actors before use is definitely a good idea, but some of them think that it does not have to be so.
More exactly, four thinks that the declaration is not needed, the remaining 15 is strongly in favor of it. Nobody selected the size dependent answer.
Because such a big number of respondents chose the declaration, it should be used before an actor first occurs.
General thoughts It was possible that someone wanted to add something which was not covered by the questions.
Question: If you have anything to add about the use case diagrams...
Choices: open question
Nobody provided anything about use case diagrams in terms of a comment or similar thing.
Class diagrams In this part of the survey some questions regarding class diagrams were asked. The questioning was more detailed, because class diagrams are one of the more common diagram types encountered and are talked about for a longer period of time (this claim is based on the experience of studying software engineering at Masaryk university and is a personal opinion).
Method declaration style As is apparent from the PlantUML syntax overview, two styles of method declarations are possible and the same is true for the type declarations. One of course might be preferred by the responding people.
36
The first question introduction text was:
The following two diagrams are identical:
@startuml
Object <|-- ArrayList
Object : equals()
ArrayList : Object[] elementData
ArrayList : size()
@enduml and
@startuml class Object { equals()
} class ArrayList {
Object[] elementData size() }
Object <|-- ArrayList
@enduml
Question: Which of the method declaration styles looks clearer to you?
Choices: The first, The second using curly brackets, It is not important
The second question introduction text was:
The two following diagrams tell the same information:
@startuml class Flight { flightNumber : Integer departureTime : Date
}
@enduml
37 and
@startuml class Flight {
Integer flightNumber
Date departureTime
}
@enduml
Question: Which of the styles looks more practical when browsing the diagram?
Choices: Version with types after member names, Version with type names before member names, I don't see a difference
Clearly, the method declaration syntax using curly braces is preferred, despite the win not being absolute.
6 of the answers favored the style without enclosing the class body in curly braces), the rest favored the enclosure of fields in blocks. Nobody did not claim that this matter is not important.
The distribution of answers is similar when we look at the type declaration style. The classic c-like style with types before method/variable names wins, but some preferences of the second style exist.
8 of the answers preferred type names after member names, the remaining 11 preferred the c-like style. No indecisive answers were submitted.
There was no evidence of a correlation between the previous two question's answers.
Clearly, when writing a diagram for a visually impaired reader, it's better to prefer the curly style. The situation of type declarations is not as clear, but a preference for the c-like syntax exists, however it is quite possible that when collaborating with a person on a diagram, preference for the second style may appear.
Bigger diagram understanding Because class diagrams are some of the more likely to get bigger (more than 5 classes each with two or three fields), it was interesting how the people will answer some questions about a bigger diagram.
The section introductory text was:
All the following questions refer to the following diagram:
@startuml class Vehicle {
Bool locked
38
Bool open
String identifier
} class Car {
Int passenger_count
} class Truck {
Int cargo_capacity
} class Person {
String name
} class Driver {
String license_number
} class Cargo
Vehicle <|-- Car
Vehicle <|-- Truck
Person <|-- Driver
Vehicle -- Driver : drives <
Car -- Person : passenger(s) >
Vehicle -- Cargo : has >
@enduml
Question: How many classes does the diagram contain?
Choices: open question
Question: How many parent classes (e. g. classes without a parent) is in the diagram?
Choices: open question
Question: Which syntax changes would help in understanding?
39
Choices: Inheritance declaration in the class header, something like Class List extends Object), The possibility to specify class relations in the class block, Other
The visual form of the class diagram follows for convenience in figure 27.
Figure 27 - The class diagram used in the survey
The results were surprising. Only a handful of responses contained the correct class count.
The following table summarizes them:
Class count Number of answers 2 3 6 7 7 9 Unfortunately, no explanation for the 2 and 7 answers was posted.
And identifying the parent classes was more complex still, there was no correct answer, however some of them with the value of 2 could probably be interpreted as the omission of the Cargo class which has no children in the diagram and is just mentioned without any fields.
The answers follow:
40
Parent class count Occurrences 1 2 2 11 3 1 5 4 6 1 When respondents were asked about the syntax improvements which would help, all concluded that having the relationships after the classes is confusing. The feature to specify all relationships in the class body was not as often, but inheritance specification possibility was ubiquitous.
All 19 respondents wanted the extension syntax change, 6 of them extended the requirement to all relations.
From those answers it is clear that finding the inheritance relationships after all the class bodies is not a favorite think for visually impaired students and an improvement would help.
Other thoughts The question regarding the syntax changes definitely did not cover all syntax change possibilities, so there the respondents could express themselves in more detail.
Question: If you want to add something about class diagrams, do so.
Choices: open question
No additional information was filled in the open question text fields regarding class diagram syntax or any other syntax improvement suggestions.
Component diagrams In this section of the form the components diagrams were briefly discussed.
Keyword usage confirmation The PlantUML syntax once again allows omitting the keywords. So, this question was there to determine whether the keywords are in any way useful.
Question introductory text:
It probably starts to be a little bit boring, but let's have the following diagrams:
@startuml
[Database]
[Transaction monitor]
() "Filesystem"
[Database] ..> Filesystem : use
@enduml and
41
@startuml component [Database] component [Transaction monitor] interface "Filesystem"
[Database] ..> Filesystem : use
@enduml
Question: Which of the syntax forms is clearer?
Choices: First option, Second option, Does not matter
Given the previous answers it was not a big surprise that component type declaration using keywords was preferred, although not exclusively.
14 out of the 19 users preferred the usage of keywords, the rest did not saw a difference, but nobody chose the first syntactic form with punctuation.
Whenever a keyword for the component type (component, interface etc.) can be used, it is according to the results highly advisable to do so.
Other thoughts Not everything was covered, so someone could add something about the component diagrams.
Question: Anything to say about component diagrams? Let me know.
Choices: open question
There were zero additional notes regarding the component diagram syntax.
Closing questions This part of the survey wanted to know whether the usefulness of PlantUML was in any way altered and there was also place for some thoughts that did not fit anywhere else.
Question: Did this form manage to change your opinion about PlantUML?
Choices: Yes, Probably yes, Probably no, No
Question: If it managed, how?
Choices: open question
Question: If you want to add anything about PlantUML, do so here.
Choices: open question
The view of UML was not altered by the questions which means that when asked whether the questions changed their view of PlantUML, all 19 replied that probably not.
42
Nobody provided any additional comments.
Visual aspects of the PlantUML output Even if the diagram would be in the ideal form for visually impaired users, if the graphical output would not look at least decent, the not impaired colleagues would not enjoy the collaboration much.
To gather some data on the appearance of the resulting diagrams one of the seminar tutors of software engineering was asked for comments.
More exactly the asking was done in an e-mail to Mgr. Dalibor Toth.
Unfortunately, not much data was gathered in form of advices and suggested defaults.
Despite not much of a success one advice regarding class diagrams was received.
In a bigger diagram the top to bottom ordering may look odd. It can be changed by applying the left to right direction like this:
@startuml left to right direction class Vehicle {
Bool locked
Bool open
String identifier
} class Car {
Int passenger_count
} class Truck {
Int cargo_capacity
} class Person {
String name
} class Driver {
String license_number
}
43 class Cargo
Vehicle <|-- Car
Vehicle <|-- Truck
Person <|-- Driver
Vehicle -- Driver : drives <
Car -- Person : passenger(s) >
Vehicle -- Cargo : has >
@enduml
When this version of the class diagram from the survey is rendered it results in figure 28.
Figure 28 - A left to right ordered class diagram
Another attempt to obtain some more feedback about the visual output consisted of some sighted people, mainly my family. The questioning was performed in a face to face meeting.
After trying to explain the visual form of the diagram, which was not much successful in its own right, everyone concluded that he does not want to see UML diagrams for the rest of their life. This might be an interesting sociological result; however, it brings nothing for this work.
Conclusions This work first introduced UML as a general concept. Then it looked on the approaches that can be employed when presenting UML to a visually impaired student.
In the section named Standard tools a research of the existing tools was performed with the results that the existing visual tools can have the user interface accessible to some degree, but the accessibility of the diagram display interface is abysmal.
44
Also, a study between blind students about one specific tool and its possible enhancements and usage recommendations was performed.
Despite the results not being the same from all participants, it was possible to infer some conclusions about visually impaired UML students.
First, all of them met with UML at university and probably do not use it really often, as can be seen from the frequencies of UML usage, which can indicate that not counting the university courses, the respondents do not use UML for any projects which require frequent diagram interactions.
When the PlantUML syntax allows usage of a keyword and a symbol, the keywords are clearly preferred. The question of forward declarations does not have as much a clear answer, but the preference for forward declaration exists.
But probably the most important outcome are the class diagram syntax extension suggestions. As was obvious from the diagram understanding check, the requirement of relation specification (including parent child relations) after the class bodies caused a major understanding issue.
A future project could thus implement the syntax changes of PlantUML and do a study how the changes improved the user base comfort while reading the new syntactic elements and whether those changes were as successful . It could also look at other visually impaired people groups, namely those with at least some usable sight and analyze the graphical output from that perspective.
Another goal would be to develop the previously mentioned PlantUML development environment including syntax checking and some sort of tree representation of the diagram entities.
The last section briefly touched the visual aspects of the PlantUML output, specifically the class diagrams where the size grows most often.
So far, no discussion of the mentioned changes occurred on the PlantUML forum (23). Asking of those questions on the forum could be a part of some future work.
The advice is basically that in a bigger diagram left to right direction sometimes helps.
Appendix
PlantUML Installation note Just to avoid the same errors which I faced, PlantUML requires Graphviz for generation of almost all diagram types except sequence diagrams and the new activity diagrams.
Unfortunately, this error (and maybe others) are reported only in the generated images, so forgetting the Graphviz installation is not as hard and setting the GRAPHVIZ_DOT environment variable may also be forgotten easily.
45
Resources 1. Brief Summary of UML. [book auth.] James Rumbaugh, Ivar Jacobson and Grady Booch. Unified Modeling Language Reference Manual, The (2nd Edition). s.l. : Pearson Higher Education, 2004.
2. ISO/IEC 19501:2005 - Information technology - Open Distributed Processing - Unified Modeling Language (UML) Version 1.4.2. [Online] 01 04 2005. [Cited: 23 10 2017.] https://www.iso.org/standard/32620.html.
3. BROOKSHIRE, Robert G. TEACHING UML DATABASE MODELING TO VISUALLY IMPAIRED STUDENTS. Issues in Information Systems. 2006, Vol. 07:1.
4. king, Alasdair. TeDUB and Accessible UML. [Online] [Cited: 03 11 2015.] http://www.alasdairking.me.uk/tedub/index.htm.
5. Textual UML Tools. Modeling Languages. [Online] [Cited: 03 11 2015.]
6. PlantUML. [Online] 01 11 2011. [Cited: 03 11 2011.] http://plantuml.com/plantuml.
7. NV Access. [Online] 2017. [Cited: 07 11 2017.] https://nvaccess.org.
8. ArgoUML. Tigris. [Online] 15 12 2011. [Cited: 23 10 2017.] http://argouml.tigris.org/.
9. Enterprise Architect. UML tools for software modelling. [Online] 2017. [Cited: 23 10 2017.] http://argouml.tigris.org/.
10. Rational Rhapsody family. IBM. [Online] 2017. [Cited: 07 11 2017.] https://www- 03.ibm.com/software/products/en/ratirhapfami.
11. Rational Software Architect Designer . IBM. [Online] 2017. [Cited: 07 11 2017.] https://www- 03.ibm.com/software/products/en/ratsadesigner.
12. Ogheorghies. Ogheorghies/MetaUML. Github. [Online] 07 07 2015. [Cited: 03 11 2015.] https://github.com/ogheorghies/MetaUML.
13. Ogheorgies. Activity. Github. [Online] 16 06 2015. [Cited: 03 11 2015.] https://github.com/ogheorghies/MetaUML/wiki/Activity.
14. Graphviz – Graph Visualization Software. [Online] 13 04 2014. [Cited: 03 11 2015.] http://www.graphviz.org/.
15. Scalable Vector Graphics (SVG) 1.1 (Second Edition). World Wide Web Consortium. [Online] 16 07 2011. [Cited: 03 11 2015.] http://www.w3.org/TR/SVG/.
16. Sequence diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/sequence-diagram.
17. Use case diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/use-case-diagram.
18. Class diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/class-diagram.
46
19. New activity diagram Beta syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/activity-diagram-beta.
20. Component diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/component-diagram.
21. State diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/state-diagram.
22. program-l: V.I. Programmers Discussion List. Freelists. [Online] 2017. [Cited: 11 11 2017.] https://www.freelists.org/list/program-l.
23. PlantUML Q&A. [Online] 2017. [Cited: 5 12 2017.] http://forum.plantuml.net/.
47