Workshop on Graphical Documentation for Programmers: Assessing the Efficacy of UML Diagrams for Program Understanding Shihong Huang
Scott Tilley
Department of Computer Science University of California, Riverside
[email protected]
Department of Computer Sciences Florida Institute of Technology
[email protected]
Programmers often use graphical forms of documentation that rely on software visualization techniques to make complicated information easier to understand. However, it is an open question exactly which types of graphical documentation are most suitable for which types of program understanding tasks (and in which specific usage contexts). The Unified Modeling Language (UML) is the de facto standard for modeling modern software applications. This workshop (the fourth in a series on graphical documentation for programmers) focuses on discussing techniques for the efficacy of UML diagrams in aid of program understanding. The majority of the workshop will involve participants analyzing a series of UML diagrams and answering a detailed questionnaire concerning a hypothetical software system.
syntax and semantics of the language’s visual building blocks of things, relationships, and diagrams [1]. Graphical representations of software artifacts, as captured in UML diagrams, are often advocated as an effective means of aiding program understanding. While there is no doubt that such visual images can be artistically pleasing to the eye, there is little scientific evidence that such forms of graphical documentation are superior to textual documentation in effectively aiding program understanding. There are many unresolved research issues related to which types of diagrams are most appropriate for aiding program understanding. More specifically, it is unknown exactly which forms of graphical documentation are most suitable for which types of program understanding tasks, and in which specific usage context.
K e y w o r d s : program understanding, documentation, UML, assessment
2. Workshop Structure
Abstract
graphical
1. Introduction There are two broad categories of documentation that are used as an aid in program understanding. The first category is textual, exemplified by printed manuals and user guides. A more flexible form of textual documentation is electronic, such as HTML or XML files, which permit activities such as automated indexing and the creation of hypertext links between document fragments. The second category of documentation is graphical, exemplified by UML diagrams commonly used during the design phase of the software lifecycle. Graphical documentation relies on a variety of software visualization techniques to make complicated information easier for the developer to understand (e.g., highlighting complex dependencies in a large application by drawing nodes, arcs, and related artifacts on a computer display). In UML, this is done by relying on the well-defined
This workshop is focused on assessing the efficacy of UML diagrams in aiding the understanding of a largescale software system. Specifically, we’re interested in finding out how much a set of UML diagrams can tell a professional developer who has some knowledge of the UML about an existing system – one that the developer didn’t design or construct. In other words, assessing how useful the UML is in helping to understand a legacy system. The UML diagrams in question might exist from earlier designs, or they may be created after the fact through sophisticated reverse engineering. The workshop will be in two parts. The first part will be a short summary of the preliminary results from related workshops at SIGDOC 2001 [4], SIGDOC 2002 [3], and Dagstuhl 2003 [2]. The focus of each of these workshops was broadly on graphical documentation for programmers, but each specific instance had a slightly different focus. The IWPC 2003 workshop is a refinement of the Dagstuhl 2003 event. The second and most important part of the workshop is a participatory experiment. Each attendee will be
Proceedings of the 11 th IEEE International Workshop on Program Comprehension (IWPC’03) 1092-8138/03 $17.00 © 2003 IEEE
provided with a set of UML diagrams that depict an existing software system, and a set of questions regarding the attributes of the system. The goal is to assess the qualitative efficacy of UML diagrams in aiding program understanding.
3. Workshop Participants The ideal mix of workshop participants would be representatives from academia (students and faculty) and from industry. The participants should have an interest in the subject areas of program understanding, graphical documentation and visual modeling, and empirical studies. The only requirement is a willingness to actively participate in the workshop discussions, and some knowledge of the UML. NOTE: UML diagrams are a key part of the experiment in the second part of the workshop. Therefore, workshop participants should have a reasonable knowledge of the core building blocks of the UML. Since this is short workshop, there will be little time to provide UML training. However, we will not exclude anyone from participating. Active participation from industrial representatives in particular would greatly improve the workshop’s tenor. Many companies are standardizing on UML as a key technology in their software development processes. Since the systems they develop are typically of substantial size, and will likely be maintained for some years to come, as assessment of the long-term usefulness of UML diagrams for their organization would be very useful.
4. Workshop Results The results from this workshop, and the related workshop listed above, will be collected together and published in a suitable forum for dissemination.
5. Workshop Organizers Two people will organize the workshop: Shihong Huang from the University of California, Riverside, and Scott Tilley from the Florida Institute of Technology. Shihong Huang is Ph.D. candidate in the Department of Computer Science at the University of California, Riverside (UCR). Her research interests include reverse engineering for program understanding, software documentation for real-time systems, and multilingual Web sites. She was the primary researcher on a collaborative project related to system redocumentation involving UCR and BMW Group. Scott Tilley is an Associate Professor in the Department of Computer Sciences at the Florida Institute of Technology. He is also Principal of S.R. Tilley & Associates, an information technology consultancy based on Florida’s Space Coast. He has a Ph.D. from the University of Victoria. He is the General Chair for the 5 th International Workshop on Web Site Evolution (WSE 2003) and the past Program Chair for the 6th International Workshop on Program Comprehension (IWPC’98).
References [1] IBM Corp. “UML Resource Center”. Online at http://www.rational.com/uml. [2] Tilley, S. and Huang, S. “Assessing the Efficacy of Software Architecture Visualization Techniques for Recovered Artifacts.” Dagstuhl Seminar 03061: Software Architecture Recovery and Modeling (Feb. 2 – 7, 2003; Schlöss Dagstuhl, Germany). [3] Tilley, S. and Wong, K. “Workshop on Graphical Documentation for Programmers”. Held in conjunction with The 20th Annual International Conference on Systems Documentation (SIGDOC 2002: October 21, 2002; Toronto, Canada). [4] Tilley, S.; Smith, D.; and Thomas, B. “Documentation for Software Engineers: What is Needed to Aid System Understanding?”. Held in conjunction with The 1 9th Annual International Conference on Systems Documentation (SIGDOC 2001: Santa Fe, NM; October 21-24, 2001).
Proceedings of the 11 th IEEE International Workshop on Program Comprehension (IWPC’03) 1092-8138/03 $17.00 © 2003 IEEE
