Masarykova univerzita
Fakulta informatiky
UML modeling tools for blind people
Bakalářská práce
Lukáš Tyrychtr 2017
MASARYKOVA UNIVERZITA Fakulta informatiky
ZADÁNÍ BAKALÁŘSKÉ PRÁCE
Student: Lukáš Tyrychtr
Program: Aplikovaná informatika
Obor: Aplikovaná informatika
Specializace: Bez specializace
Garant oboru: prof. RNDr. Jiří Barnat, Ph.D.
Vedoucí práce: Mgr. Dalibor Toth
Katedra: Katedra počítačových systémů a komunikací
Název práce: Nástroje pro UML modelování pro nevidomé
Název práce anglicky: UML modeling tools for blind people
Zadání:
The thesis will focus on software engineering modeling tools for blind people, mainly at com•monly used models -UML and ERD (Plant UML, bachelor thesis of Bc. Mikulášek -Models of Structured Analysis for Blind Persons -2009). Student will evaluate identified tools and he will also try to contact another similar centers which cooperate in this domain (e.g. Karlsruhe Institute of Technology, Tsukuba University of Technology). The thesis will also contain Plant UML tool outputs evaluation in three categories -students of Software engineering at Faculty of Informatics, MU, Brno; lecturers of the same course; person without UML knowledge (e.g. customer) The thesis will contain short summary (2 standardized pages) of results in English (in case it will not be written in English).
Literatura:
ARLOW, Jim a Ila NEUSTADT. UML a unifikovaný proces vývoje aplikací : průvodce analýzou a návrhem objektově orientovaného softwaru. Brno: Computer Press, 2003. xiii, 387. ISBN 807226947X.
FOWLER, Martin a Kendall SCOTT. UML distilled : a brief guide to the standard object mode•ling language. 2nd ed. Boston: Addison-Wesley, 2000. xix, 186 s. ISBN 0-201-65783-X.
Zadání bylo schváleno prostřednictvím IS MU. 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 a ERD 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, ERD, nástroje, nevidomí, přístupnost, PlantUML Table of contents 1 Introduction ...... 7 2 About UML ...... 7 3 About ERD...... 8 4 Current tools and state of the research ...... 8 4.1 UML and ERD diagram presentation approaches ...... 8 4.2 UML Software tools ...... 9 4.2.1 Standard tools ...... 9 4.2.2 Cooperate Modeling Environment ...... 9 4.2.3 MetaUML ...... 10 4.2.4 Graphviz ...... 11 4.2.5 SVG ...... 12 4.3 ERD software tools ...... 13 4.3.1 ERD ...... 13 4.3.2 Syntax described by Adam Mikulášek ...... 14 5 PlantUML ...... 15 5.1 Import & Export of PlantUML documents ...... 15 5.2 Integration of PlantUML with other tools ...... 16 5.2.1 PlantUML Eclipse Editor ...... 16 5.3 Syntax ...... 16 5.3.1 Sequence diagrams ...... 16 5.3.2 Use case diagrams ...... 18 5.3.3 Class diagrams ...... 20 5.3.4 Activity diagrams ...... 23 5.3.5 Component diagrams ...... 25 5.3.6 State diagrams ...... 27 5.3.7 Other diagram types ...... 28 5.4 The syntax choices ...... 29 6 PlantUML and visually impaired users ...... 29 6.1 The questions ...... 29 6.2 The subjects ...... 29 6.2.1 Universities ...... 29 6.2.2 International programming groups ...... 29 6.3 The questioning ...... 29
5
6.4 The questions and their answers ...... 30 6.4.1 The general questions ...... 30 6.4.2 Encountered UML Tools ...... 30 6.4.3 Sequence diagrams ...... 31 6.4.4 Use case diagrams ...... 33 6.4.5 Class diagrams ...... 34 6.4.6 Component diagrams ...... 38 6.4.7 Closing questions ...... 39 7 Visual aspects of the PlantUML output ...... 39 7.1 The questions and their answers ...... 40 7.1.1 You and UML ...... 40 7.1.2 Use case diagrams ...... 40 7.1.3 State diagrams ...... 43 7.1.4 Activity diagrams ...... 43 7.1.5 Class diagrams ...... 44 7.1.6 Sequence diagrams ...... 46 7.1.7 Component diagrams ...... 47 7.1.8 Final questions ...... 48 8 Evaluation of ERD tools ...... 48 9 Practical diagram presentation approaches...... 49 9.1 Masaryk university ...... 49 9.2 Karlsruhe Institute of Technology ...... 49 10 Conclusions ...... 49 11 Appendix ...... 50 11.1 PlantUML Installation note ...... 50 12 Resources ...... 51
6
1 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 also explores the state of textual representation of ERD diagrams.
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.
2 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 an 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.
1. 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. 2. 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. 3. 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. 4. 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.). 5. 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. 6. 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. 7. 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.
7
8. 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. 9. 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. 10. A component diagram shows the relationships between larger system components (databases, application servers etc.) and the interfaces used. 11. 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. 12. The package diagram is used to show the application namespace structure and the imports between the individual packages. 13. The composite structure diagram is used to show the composite structure of a class. 14. 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.
3 About ERD ERD (Entity relationship diagram) is one of the diagram types used in structured analysis of a software system. It depicts a schema of a database (the stored entities, attributes and connections between the entities). There are three levels of detail of the ERD diagram:
1. Conceptual, which shows only the connections between entities, the entities themselves and the most important attributes. 2. Technological ER diagram on the other hand shows all attributes 3. And a physical ERD diagram shows low level database details.
4 Current tools and state of the research
4.1 UML and ERD diagram presentation approaches When it comes to presenting the UML or ERD 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.
Of course, a verbal description is also possible. The comprehension of such description is however dependent on the skills of the describing person.
8
4.2 UML 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 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 more promising tools.
4.2.1 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).
4.2.1.1 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.
4.2.1.2 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.
4.2.1.3 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.
4.2.2 Cooperate Modeling Environment The Cooperate modeling Environment (12) is an initiative of the Cooperate project (13) to create an environment where sighted and visually impaired users alike could collaborate on an UML model. The software is a plugin for the Eclipse integrated development environment. Users of the software can edit the models in a text form or in a graphical view and the changes are automatically reflected in the other form. So far, the software supports class, use case and component diagrams. The textual
9 syntax generally prefers keywords over punctuation to denote meaning. But as all the others explored syntaxes, it requires the definition of the elements (classes, use cases) before any associations can be created. On the other hand, the textual editor supports autocompletion, syntax checking with quick fixes if applicable and an outline view. The project seems so far active and there are plans on importing Enterprise Architect models in the future.
4.2.3 MetaUML MetaUML (14) 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 (15), whose code follows for convenience.
Listing 1 – MetaUML source code example
Begin.b; Activity.eat("Eat something good", "from the kitchen"); Branch.enough; Fork.fork("h", 50); Activity.read("Read a book"); 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.
10
Figure 1 - Example of a MetaUML diagram
4.2.4 Graphviz Graphviz (16) 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, listing 2 is an example of a simple class diagram using Graphviz syntax:
Listing 2 – Source code of a 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.
11
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.
4.2.5 SVG SVG (17) 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 is shown in listing 3 (direct output from PlantUML):
Listing 3 – A diagram written directly in SVG
12
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.
4.3 ERD software tools In theory, it is possible to represent the ER diagrams in the same ways as the UML diagrams. However, there are only standard tools, or tools converting from a text file, no attempts for a specialized tool were found. The following sections will therefore describe the few ERD tools which take as input a text file and produce a graphical output.
4.3.1 ERD ERD (18) is a tool written in haskell, which produces an image representation of an ERD diagram given its textual form. The syntax is quite readable, see listing 4 for an example.
Listing 4 – an example of the ERD tool syntax
[Person] *name height weight +birth_location_id
[Location] *id city state
13 country
Person *--1 Location
The syntax supports primary and foreign keys, relationships and attribute definitions. There is no syntax support for specifying data types, they must be specified as labels.
4.3.2 Syntax described by Adam Mikulášek A previous bachelor thesis of Adam Mikulášek (19) is also relevant. This work was an attempt to define a grammar for the various types of diagram in structured analysis. It also rightly pointed the differences in understanding of visually impaired users (e. g. mostly linear for visually impaired users and spatial for sighted users).
4.3.2.1 ER diagrams The suggested syntax for ER diagrams is simple enough. The diagram starts with the erd keyword followed by a diagram title. Next, the line with the content entities; denotes the start of the entity definitions. Entity attributes are defined in blocks enclosed within curly brackets, the identifier before the opening bracket is the entity name. A primary key is preceded by an @ sign before the attribute name. The relationships follow after the relationships; line in the form:
Label left side >right side card [left cardinality] [right cardinality]
An example follows in listing 5.
Listing 5 – an example of the syntax created by Adam Mikulášek erd shop (*erd of an iternet shop*); entities; customer { @customer_code, first_name, last_name, adress } order { @order_number, customer_code (*foreign key from the customer entity*), date, payment_type, state } supplier { @supplier_code, name, adress } order_item { @order_number (foreign key from the order entity*), @item_code (*foreign key from the item entity*), quantity } item_supplier { @item_code (*foreign key from the item entity*), @supplier_code (*foreign key from the supplier entity*), price, last_shipment_date } item { @item_code, name, description,
14
stock_quantity, minimum_stock } relationships; orders customer >order card [1,1] [0,n]; contains order >order_item card [1,1] [1,n]; supplies supplier >supplier_item card [1,1] [0,n]; is_ordered order_item >item card [0,n] [1,1]; is_supplied item_supplier >item card [1,n] [1,1];
The syntax is defined rigorously enough that writing a visualization tool could be definitely done, however creation of such a tool was out of scope of the thesis.
The syntax has no concept of foreign keys. The relationships give an indication that a foreign key should exist, but they do not specify which of the entity's attribute holds the foreign value. The original thesis notes the existence of various keys, but it provides only the syntax for primary keys. This limitation had to be solved at least already once in my software engineering classes, so an extension of the syntax rules (for example using a # to denote a foreign key) would probably be needed before wider adoption could be achieved. The ERD tool (described in section 4.3.1) was not mentioned, but it is understandable, the GitHub repository was created in October of 2014 and the work was finalized already in 2009.
4.3.2.2 State diagrams The thesis also presents a syntax for state transition diagrams. The syntax is also quite simple, see listing 6 for an example.
Listing 6 – Example of a state diagram in the syntax suggested by Adam Mikulášek std title; (entry state, condition >action, intermediate state; Intermediate state, condition >action, end state)
The usage of braces to denote the ending and starting states is a succinct way to do so, however, given the default screen reader verbosity settings can be missed very easily. On the other hand, for a simple state diagram (without composite states etc.) it is comparable to the PlantUML syntax and is somewhat easier to learn.
5 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.
5.1 Import & Export of PlantUML documents Not much has been done in this regard. There is an experimental support for export of class diagrams to XMI, but as the related PlantUML wiki page (20) notes, the implementation of XMI in UML applications is not standardized enough, so just for ArgoUML and StarUML two command line flags were necessary, because the tools differed in interpretation of XMI association data. On the other
15 hand, if an export without associations is enough, the export should be sufficient despite the feature being in alpha stage of development.
5.2 Integration of PlantUML with other tools When it comes to PlantUML integrations with editors, wiki systems and other software, there are definitely some choices. There is an integration with the Eclipse integrated development environment (21), Visual studio code (22), and many more listed at (23). The editor integrations generally support live preview of the diagram, syntax highlighting and export to an image or XMI if applicable.
The second broad category of integrations are plugins for viewing the rendered image for example on a wiki, or forum, instead of displaying the source code.
5.2.1 PlantUML Eclipse Editor The PlantUML Eclipse Editor (24) is an attempt started by the Cooperate project (13) to create an extension of the previously developed PlantUML Eclipse integration. The features include syntax highlighting, outline presentation and basic autocomplete. Unfortunately, the development appears to be stalled, because the last commit occurred on November 1st, 2016 and the focus of the Cooperate project moved to the Cooperate Modeling Environment.
5.3 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.
5.3.1 Sequence diagrams A basic sequence diagram would be written as listing 7 shows. 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.
Listing 7 – a basic sequence diagram Figure 4 - Simple sequence diagram @startuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request Alice <-- Bob: another authentication Response @enduml
16
You can also define actors before they appear, which is shown in listing 8. Listing 8 also shows all of the five kinds of actors: actor, boundary, control, entity and database. The differences of them are mainly in the display and semantic usage. Figure 5 shows the visual differences.
Listing 8 – Other entity types in a sequence Figure 5 - Example of the various sequence diagram diagram actor types @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
It is also possible to rename the actors using the as keyword. This is shown in listing 9. It displays as is shown in figure 6.
Listing 9 – usage of actor renaming Figure 6 - Example of an sequence diagram with @startuml renamed actors actor Alice as A actor Bob as B A -> B: Authentication Request B --> A: Authentication Response
A -> B: Another authentication Request A <-- B: another authentication Response @enduml
17
A message with the same participant on both sides is also valid and is shown in listing 10. And it looks as is shown in figure 7.
Listing 10 – a message to self Figure 7 - sequence diagram with self message @startuml Alice->Alice: This is a signal to self @enduml
Some other features are also available, such as changing the arrow style, adding notes etc.
The rest is described in (25).
5.3.2 Use case diagrams The individual use cases are defined as listing 11 shows. 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.
Listing 11 – a basic use case diagram Figure 8 - Simple use case diagram @startuml (First usecase) (Another usecase) as (UC2) usecase UC3 usecase (Last\nusecase) as UC4 @enduml
18
The situation with actor definition is somewhat similar. They can be defined either by enclosing them between :, or it is possible to use the actor keyword. Listing 12 uses both styles. And they look like as figure 9 shows.
Listing 12 – actors in a use case diagram Figure 9 - Use case diagram with actors @startuml :First Actor: :Another\nactor: as Men2 actor Men3 actor :Last actor: as Men4 @enduml
The linking is done using arrows. The number of dashes affects the arrow length. As you can see from this example shown by listing 13, declaration is not required. The visual result is shown by figure 10.
Listing 13 – Actor and use case linking Figure 10 - Use case diagram with links @startuml User -> (Start) User --> (Use the application) : A small label :Main Admin: ---> (Use the application) : This is\nyet another\nlabel @enduml
19
It is possible to declare extension of actor or use cases using the <|-- symbol. An example is shown in listing 14. The visual result looks like figure 11.
Listing 14 – use case and actor extension Figure 11 - Use case actor extension @startuml :Main Admin: as Admin (Use the application) as (Use) User <|-- Admin (Start) <|-- (Use) @enduml
Some other features include adding notes, visual style adjustment etc. The complete definition of the syntax is at (26).
5.3.3 Class diagrams First off, the relationships between classes are defined as is shown in listing 15, 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
Figure 13 - Class relations
Listing 15 – class relations
@startuml Class01 <|-- Class02 Class03 *-- Class04 Class05 o-- Class06 Class07 .. Class08 Class09 -- Class10 @enduml
20
Labels on relations are added after a : following the relation. Cardinality is denoted on the respective sides of the relation symbol as is shown by listing 16. This usage displays as is shown by figure 13.
Listing 16 – class relationships Figure 14 - Class relations with labels and cardinality @startuml Class01 "1" *-- "many" Class02 : contains Class03 o-- Class04 : aggregation Class05 --> "1" Class06 @enduml
There are two possibilities how to declare fields and methods. The first uses : after the class name as listing 17 demonstrates. It displays as is shown by figure 14.
Listing 17 – class fields, first style Figure 15 - Class fields @startuml Object <|-- ArrayList Object : equals() ArrayList : Object[] elementData ArrayList : size() @enduml
The second approach uses brackets as is shown by listing 18. Both type declaration styles are possible and could theoretically appear in a single diagram. This class diagram displays as is shown by figure 15.
Listing 18 – class fields, second style Figure 16 - Class fields, curly brackets form @startuml class Dummy { String data void methods() }
class Flight { flightNumber : Integer departureTime : Date } @enduml
21
Visibility is controlled using a character before the method/field name where means private, # means protected, ~ means package private and + means public. The visibilities are used in listing 19 whose output is shown by figure 16.
Listing 16 – class field visibilities Figure 17 - Class field visibility @startuml class Dummy { -private #protected ~packagePrivate() +public() } @enduml
Static and abstract fields also work as listing 20 demonstrates. Those elements display as figure 17 shows.
Listing 20 – static and other field modifiers Figure 18 - Abstract and static class fields @startuml class Dummy { {static} String id {abstract} void methods() } @enduml
Usage of abstract classes and interfaces is also possible, they are used in listing 21. The listing also shows usage of enumerations and annotation definitions and renders as is shown in figure 18.
Listing 21 – miscellaneous class syntax examples
@startuml abstract class AbstractList abstract AbstractCollection 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
22
Figure 19 - Abstract classes, interfaces, enumerations and annotations
Some other less often used features of the class syntax also exist, the complete reference is at (27).
5.3.4 Activity diagrams PlantUML has two syntax flavors for the activity diagram. This section will only describe the new syntax.
A basic diagram looks like listing 22. 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.
Listing 22 – basic activity diagram Figure 20 - Basic activity diagram @startuml :Hello world; :This is defined on several lines; @enduml
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 listing 23. Those syntactic elements display as figure 20 shows.
23
Listing 23 – conditions in an activity diagram
@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 Figure 21 - Activity diagram with conditionals and explicit start and stop markers
A do while loop is used in listing 24 and is shown in figure 21.
Listing 24 – A do while loop Figure 22 - Activity diagram with a do while loop @startuml start repeat :read data; :generate diagrams; repeat while (more data?) stop @enduml
24
And a representation of a while loop is shown in listing 25, whose rendering is shown in figure 22.
Listing 25 – a while loop Figure 23 - Activity diagram with a while loop @startuml start while (data available?) :read data; :generate diagrams; endwhile stop @enduml
Some other features regarding parallelism and visual parameters exist, they are described at (28).
5.3.5 Component diagrams A basic component diagram in the PlantUML syntax is presented in listing 26. 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.
Listing 26 – a simple component diagram Figure 24 - Simple component diagram @startuml DataAccess - [First Component] [First Component] ..> HTTP : use @enduml
Grouping is also available using a few flavors which are showcased by listing 27. This case displays as is shown in figure 24.
25
Listing 27 – grouped component diagram
@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" { [Frame 4] } }
[Another Component] --> [Example 1] [Example 1] --> [Folder 3] [Folder 3] --> [Frame 4] @enduml
26
Figure 25 - Component diagram with the various grouping constructs
Other features like notes and visual control also exist, see (29) for more details.
5.3.6 State diagrams A simple state diagram is written as is shown in listing 28. The [*] symbol denotes the starting and stopping state and -> denote the transitions. This diagram is graphically represented by figure 25.
27
Listing 28 – simple state diagram Figure 26 - Simple state diagram @startuml [*] --> State1 State1 --> [*] State1 : this is a string State1 : this is another string State1 -> State2 State2 --> [*] @enduml
It is possible to create a composite state using a state block as is indicated by listing 29 And renders as is shown by figure 26.
Listing 29 – composite state Figure 27 - State diagram with composite state @startuml state NotShooting { [*] --> Idle Idle --> Configuring : EvConfig Configuring --> Idle : EvConfig } @enduml
Some color control, notes and other features are available, see (30) for the complete reference.
5.3.7 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.
28
5.4 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.
6 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.
6.1 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. 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.
6.2 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.
6.2.1 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.
6.2.2 International programming groups Because of the university students count the Program-l mailing list (31) 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.
6.3 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
29 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 reasons. The results were looked at periodically, but lastly at 11th November 2017.
6.4 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.
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.
6.4.1 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.
6.4.2 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.
30
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.
6.4.3 Sequence diagrams This section of the survey explored the syntax and other aspects of the sequence diagram syntax.
6.4.3.1 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.
6.4.3.2 Arrow directionality This question wanted to determine whether the directionality of PlantUML arrows was useful or not.
It had the following introductory text:
31
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 arrows differing only in their direction should be used whenever they appear in a diagram, or put another way, it is not advisable to change the order of entities in a diagram only because a reverse arrow is needed.
6.4.3.3 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:
32
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.
6.4.4 Use case diagrams In this part of the survey the respondents were asked some questions about use case diagrams.
6.4.4.1 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
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.
33
6.4.4.2 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.
6.4.4.3 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.
6.4.5 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).
6.4.5.1 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.
The first question introduction text was:
The following two diagrams are identical:
@startuml Object <|-- ArrayList Object : equals() ArrayList : Object[] elementData ArrayList : size() @enduml and
34
@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 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
35 is quite possible that when collaborating with a person on a diagram, preference for the second style may appear.
6.4.5.2 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 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?
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.
36
Figure 28 - 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:
Parent class count Occurrences 1 2 2 11 3 1
37
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.
6.4.5.3 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.
6.4.6 Component diagrams In this section of the form the components diagrams were briefly discussed.
6.4.6.1 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
@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
38
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.
6.4.6.2 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.
6.4.7 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.
Nobody provided any additional comments.
7 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.
Research in this area was performed on two groups of people. The first were the teachers and assistants of Software Engineering at the Masaryk university and the second group were some random people, generally without any IT background.
The survey was sent to 11 professors and assistants of PB007 (the software engineering course). Of those, 3 answered. The survey was also shared on social media sites to get some responses of non- technical people. The exact number of people which saw the survey link is not known because of
39 various social site post ordering algorithms, but at least 40 people is a good approximation. Of those, 8 answered.
The questioning used a survey common for both groups. The introductory texts briefly explained the surveyed diagram type and then presented an example diagram accompanied with some questions. The survey ran from the 4th of April 2018 to the 6th May of 2018.
7.1 The questions and their answers This section presents the survey questions and their answers. Because many of the questions are of a scale ranking type, only the averages will be presented, when relevant, averages for It people and the others will be presented.
7.1.1 You and UML The only question in this section had to identify the various people types (teachers, software engineers etc.).
Question: You met with UML
Choices: Never, A few times (for example during a software project), A lot – I work with it, A lot -I am teaching it
Answers: A lot -I am teaching it – three times, Never, also three times
7.1.2 Use case diagrams In this section the usability of use case diagrams was reviewed. The following use case diagram was used.
40
Figure 29 - First of the survey use case diagrams
Question: How would you rate the diagram understandability?
Choices: Scale from 1 to 10
Answer averages: Professors – 8, Other people – 1.3
Question: How would you rate the visual appearance of this PlantUML diagram?
Choices: Scale from 1 to 10
Answer averages: Professors – 5, Other people - 1
Question: How could be the presentation improved?
Choices: Open question
Answer: The diagram is missing the system boundary – actors should be outside of the boundary, use cases inside. Also, when a communication has an answer, a simple line should be used.
7.1.2.1 Complex diagram understanding The questions in this section were largely similar to the simple diagram case, however, they used a more complex diagram. Also, a few understanding questions were asked.
41
Figure 30 - More complex use case diagram used in the survey
Question: Who can according to the diagram above review the subject catalogue?
Choices: Any of: Student, Teacher, Assistant, Administrator
Answers: Student and assistant – three times (all answers of the professors), Student – three times (answers of the other people)
Question: Can a teacher assistant view information about members of all seminar groups of a subject in which he leads a seminar group?
Choices: Yes, No
Answers: No – three times, yes – three times (no correlation between the respondent is a professor)
Correct answer: No
Question: Can an administrator, according to the diagram above, edit student subject registrations?
Choices: Yes, No
Answers: No – five times (all the professors and one of the others), yes – only once
Correct answer: No
Question: How do you rate the understandability of this diagram?
Choices: Scale from 1 to 10
Answer averages: Professors - 4.6, Others - 2.3
Question: How could the presentation of bigger diagrams be improved?
Choices: Open question
Answer: It could use the separation boundary between use cases and actors, or it could span multiple lines.
These results show that the diagrams are quite understandable at least by people with previous UML experience, however the understandability quickly declines when a more complex diagram is presented. The answers also show some ideas for improvement of the PlantUML output, namely they suggest using multiple rows for a bigger diagram and they also suggest separating the use cases from the actors.
42
7.1.3 State diagrams In this section of the survey the understandability and visual appearance of the following diagram was tested.
Figure 31 - State diagram from the survey
Question: How would you rate the diagram understandability?
Choices: Scale from 1 to 10
Answer averages: Professors – 8, others - 2
Question: How would you rate the visual appearance of this PlantUML diagram?
Choices: Scale from 1 to 10
Answer averages: Professors – 7.6, others – 1.6
Question: How could be the presentation improved?
Choices: Open question
Answer: The forceAwake() text should not overlap the arrow.
Unfortunately, the non-technical respondents did not provide any explanations for the low scores, but the results for the group of UML assistants are quite good. Of course, the overlap with the arrow, if generally reproducible, should be reported as a PlantUML bug.
7.1.4 Activity diagrams This section was exploring the visual properties of the following activity diagram.
43
Figure 32 - Activity diagram from the survey
Question: How would you rate the diagram understandability?
Choices: Scale from 1 to 10
Answer averages: Professors – 7.6, Others – 1.4
Question: How would you rate the visual appearance of this PlantUML diagram?
Choices: Scale from 1 to 10
Answer averages: Professors – 7.3, Others – 2.1
Question: How could be the presentation improved?
Choices: Open question
Answer: Decision and action nodes are not as distinguishable, they could be more visually distinct, or the condition text could be near the node. And the data flows should be in square brackets.
The results indicate that when the person viewing the diagram has at least some UML knowledge, the understandability is alright, but could be improved. The results for the general populace however are much worse and without any explanations. The node appearance change suggestions should be reviewed and likely submitted to the creators of PlantUML or implemented in another thesis.
7.1.5 Class diagrams In this section the visual aspects of class diagrams were explored. For the survey the following more complex diagram was used.
44
Figure 33 - The class diagram used in the survey.
Question: How many classes are in the diagram?
Choices: Open question
Answers: 6 – 6 times
Correct answer: 6
Question: And how many classes without a parent it contains?
Choices: Open question
Answers: 6 – two times, 3 – four times
Correct answer: 3
Question: How would you rate the diagram understandability?
Choices: Scale from 1 to 10
Answer averages: Professors – 8.6, Others – 4.6
Question: How would you rate the visual appearance of this PlantUML diagram?
45
Choices: Scale from 1 to 10
Answer averages: Professors – 8, Others - 2
Question: The classes can easily be ordered horizontally. Do you think that it should be the default?
Choices: Yes, No, It does not matter
Answers: No – once, It does not matter – three times, yes – two times
Note: The horizontal diagram was the following:
Figure 34 - Horizontal class diagram from the survey
Question: How could be the presentation improved?
Choices: Open question
Answer: Understandability seems okay to me.
From the results it is obvious that class diagrams fared above average of other diagram types in the measured metrics.
The question of the left to right direction's usefulness stays undecided, in 50% of the answers it does not matter, but because only one is against it (unfortunately without an explanation), it probably can safely be used. It is interesting that the two yes answers came from the non-technical group.
7.1.6 Sequence diagrams This section was asking some questions about the following sequence diagram.
46
Figure 35 - Sequence diagram from the survey
Question: How would you rate the diagram understandability?
Choices: Scale from 1 to 10
Answer averages: Professors – 7, others – 1.6
Question: How would you rate the visual appearance of this PlantUML diagram?
Choices: Scale from 1 to 10
Answer averages: Professors – 7.3, others – 1.4
Question: How could be the presentation of sequence diagrams improved?
Choices: Open question
Answers:
1. A cross collides with the notation for <
The understandability scores are in average the same as all the other diagram types. For the comments, some of them (mainly related to lifelines) might actually be caused by incorrect source notation, so it should be investigated more thoroughly. The same applies for the arrow head, it is possible that it can be represented, but the visually impaired writer must be aware of the correct syntax.
7.1.7 Component diagrams In this section the questions related to the following component diagram.
47
Figure 36 - Component diagram from the survey
Question: How would you rate the diagram understandability?
Choices: Scale from 1 to 10
Answer averages: Professors – 6.6, others – 1.1
Question: How would you rate the visual appearance of this PlantUML diagram?
Choices: Scale from 1 to 10
Answer averages: Professors – 7.3, Others - 1
Question: How could be the presentation improved?
Choices: Open question
Answer: The reason for the connection arrow difference for the ftp and http interfaces is not obvious.
The average scores are not much different from the other diagrams. The comment might be more likely attributed to the diagram writer.
7.1.8 Final questions This section was the place for general questions which did not fit anywhere else.
Question: If you have anything to add, you can do so there.
Choices: Open question
Answers: None
8 Evaluation of ERD tools This section presents the applicable results of the research described in sections 6 and 7 in the context of the previously described ERD tools (see section 4.3 for the individual tool descriptions).
Both the ERD application and the syntax described by Adam Mikulášek has the issue that before specifying connections, all entities must be defined first, which, as the results in section 6.4.5.2 show,
48 can create some issues. No survey concerning ERD tools was part of the thesis, but the results described above, mainly in section 6.4.5.2 are general enough that they would very likely apply, and they clearly show that in a bigger diagram making the information related to a single entity near is preferable.
9 Practical diagram presentation approaches This section of the thesis provides an overview of a practical presentation approaches as used by some of the specialized centers for visually impaired in Czech Republic and abroad.
9.1 Masaryk university This section describes the approaches used during one of my semesters in the PB007 course.
The subject was taught in a small group of students, two completely blind and two others were only partially visually impaired. The other two were using Enterprise architect, so there is not much to talk about in the context of this thesis. The completely blind people were using mainly PlantUML, the graphic renderings were performed on the online server. In the case of ER diagrams, we were using the syntax proposed by Adam Mikulášek, with the addition for signaling foreign keys.
9.2 Karlsruhe Institute of Technology The Karlsruhe Institute of Technology was involved with creation of the Cooperate modeling environment (see section 4.2.2). So far, the Cooperate modeling environment went through a few user studies involving visually impaired users, but it is not so far used during seminars or lectures (at least according to the people involved with the project). Another method of diagram presentation used on the institute is PlantUML. Not including the software approaches, tactile diagrams are sometimes also used. The area of ER diagram presentation approaches did not undergo any research on the institute, but it is definitely planned in the future.
10 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. 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.
1. All of them met with UML at university and probably do not use it 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. 2. When the PlantUML syntax allows usage of a keyword and a symbol, the keywords are clearly preferred.
49
3. The question of forward declarations does not have as much a clear answer, but the preference for forward declaration exists. 4. 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, or the currently existing tools (mainly the PlantUML editor described in section 5.2.1) could be extended and a new maintainer could be found. Another research topic would be a research of the Collaborate Modeling environment (see section 4.2.2), concerning basically the same three categories of users as the PlantUML research (blind students, software engineering teachers, normal people).
In section 7, a survey of the visual output was described. To summarize, when the assistants and professors look at an UML diagram generated by PlantUML, they can understand it, but there are definitely possibilities for improvement. Some definite suggestions for PlantUML are in the survey sections describing use case and state diagrams. The other issues should be reviewed with more care and the correct PlantUML syntactic forms, if found, should be mentioned more in the software engineering courses. A future work could research the visual aspects, including writing some PlantUML patches to improve the situation.
So far, no discussion of the mentioned changes occurred on the PlantUML forum (32). Asking of those questions on the forum could be also a part of some future work.
The advice is basically that in a bigger diagram left to right direction sometimes helps.
11 Appendix
11.1 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.
50
12 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. Project, Cooperate. Cooperate-Project/CooperateModelingEnvironment. Github. [Online] 20 02 2018. [Cited: 20 02 2018.] https://github.com/Cooperate- Project/CooperateModelingEnvironment.
13. project, Cooperate. About. Cooperate project. [Online] [Cited: 20 02 2018.] https://www.cooperate-project.de/index.php/en/.
14. Ogheorghies. Ogheorghies/MetaUML. Github. [Online] 07 07 2015. [Cited: 03 11 2015.] https://github.com/ogheorghies/MetaUML.
15. Ogheorgies. Activity. Github. [Online] 16 06 2015. [Cited: 03 11 2015.] https://github.com/ogheorghies/MetaUML/wiki/Activity.
16. Graphviz – Graph Visualization Software. [Online] 13 04 2014. [Cited: 03 11 2015.] http://www.graphviz.org/.
17. 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/.
51
18. Gallant, Andrew. BurntSushi/erd. Github. [Online] 2014. [Cited: 14 02 2018.] https://github.com/BurntSushi/erd.
19. Mikulášek, Adam. Modely strukturované analýzy pro nevidimé. [Online] 2009. [Cited: 14 02 2018.] http://is.muni.cz/th/134645/fi_b/.
20. Support of XMI. PlantUML. [Online] [Cited: 13 02 2018.] http://plantuml.com/xmi.
21. Integration with Eclipse. PlantUML. [Online] [Cited: 13 02 2018.] http://plantuml.com/eclipse.
22. PlantUML. Visual studio marketplace. [Online] [Cited: 13 02 2018.] https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml.
23. Tools using the PlantUML language. PlantUML. [Online] [Cited: 13 02 2018.] http://plantuml.com/running.
24. project, Cooperate. Cooperate-Project/plantuml-eclipse-xtext. Github. [Online] 1 11 2016. [Cited: 20 02 2018.] https://github.com/Cooperate-Project/plantuml-eclipse-xtext.
25. Sequence diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/sequence-diagram.
26. Use case diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/use-case-diagram.
27. Class diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/class-diagram.
28. New activity diagram Beta syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/activity-diagram-beta.
29. Component diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/component-diagram.
30. State diagram syntax and features. PlantUML. [Online] [Cited: 23 10 2017.] http://plantuml.com/state-diagram.
31. program-l: V.I. Programmers Discussion List. Freelists. [Online] 2017. [Cited: 11 11 2017.] https://www.freelists.org/list/program-l.
32. PlantUML Q&A. [Online] 2017. [Cited: 5 12 2017.] http://forum.plantuml.net/.
52