Workshop on Graphical Documentation
GDOC 5: The 5th International Workshop on Graphical Documentation
Theme: Determining the Barriers to Adoption of UML Diagrams
Scott Tilley |
Steve Murphy |
Shihong Huang |
Abstract
The Unified Modeling Language (UML) is the de facto standard for graphically documenting modern software systems. Unfortunately, learning how to properly construct high-quality UML diagrams so that they are an effective means of communication is a challenging task. This workshop will focus on the refinement of an assessment instrument to determine the barriers to increased adoption of UML diagrams by professional software engineers, technical writers, and other project stakeholders. The ultimate goal is to develop a series of recommendations on how to improve UML diagramming practice, and how those practices can be codified in existing methodologies and supported by common tools to foster widespread use.
Keywords: graphical documentation, UML, adoption, style
Motivation
Graphical representations of software artifacts are often advocated as an effective means of documenting intent. There are many factors that can affect the suitability and efficacy of the graphical documentation in this context. For example, the layout algorithm used, edge routing, focal points, node/edge colors and shapes, etc.
The Unified Modeling Language (UML) [3] has become the de facto standard for graphically documenting modern software systems. Unfortunately, learning how to properly construct high-quality UML diagrams so that they are an effective means of communication is a challenging task. The UML itself is quite complex and difficult to master. The most recent version of the UML (UML 2.0) [7] has grown considerably since the 1.5 release, increasing the cognitive load on casual users of the stand. Indeed, even the OMG itself warns of the UML’s complexity: “… Version 2.0 [is] a large specification, and is being worked in four parts. If you're a modeler, especially if you're just starting out, you will probably find the specifications themselves a bit hard to read.”
Tool support that codifies best graphical documentation practice is somewhat limited. In part this is because there are few agreed-upon visual style guidelines for graphical documentation. Work by Ambler [1] and IBM [5][2] offers some starting points, but these are by no means widely followed. Without such a common body of knowledge of best practices, it is unsurprising that design and diagram tools that support UML provide little advanced support in terms of style, application-domain nuances, and business models.
This workshop will focus on the refinement of an assessment instrument to determine the barriers to increased adoption of UML diagrams by professional software engineers, technical writers, and other project stakeholders. Some of the initial hypotheses for the barriers to adoption are based on observations such as those mentioned above (e.g., language complexity, lack of style guidelines, limited tool support). However, the workshop will expand upon these ideas and provide a sound basis for a series on empirical studies to support or refute the resultant hypothesis.
Four recent workshops addressed the issue of graphical documentation in related contexts: SIGDOC 2001 [9], SIGDOC 2002 [8], IWPC 2003 [4], and the “GDOC 4” workshop at SIGDOC 2004 [6]. The GDOC 5 workshop continues this line of inquiry. It is part of a larger project focused on developing techniques to foster the adoption of UML diagrams for program documentation. The ultimate goal of this project is to develop a series of recommendations on how to improve UML diagramming practice, and how those practices can be codified in existing methodologies and supported by common tools to foster widespread use.
Structure
The purpose of the workshop is to foster the exchange of ideas and information in an informal setting, but with some boundaries placed on topics and time to ensure that the workshop stays on schedule.
The workshop will have a mix of short presentations and structured discussions. The workshop will begin with a short summary of the previous workshops, so that participants in this year’s workshop have a better understanding of the thread of inquiry that this workshop series represents. The remainder of the workshop will focus on the refinement of an assessment instrument to determine the barriers to increased adoption of UML diagrams by professional software engineers, technical writers, and other project stakeholders.
Relevant results from this workshop will be summarized and published in a suitable forum for public dissemination.
Participants
Anyone who attends SIGDOC 2005 and registers for the “Workshop” section of the conference is welcome to participate in the workshop. There is no formal prerequisite to participate in the workshop. Although prior knowledge of the UML would be beneficial, it is not absolutely needed. No position paper or presentation is needed. The only requirement is a willingness to actively participate in the workshop discussions.
Note: Please remember that you must register for the main conference to attend the workshop sessions.
References
[1] Ambler, S. The Elements of UML 2.0 Style. Cambridge University Press, 2005.
[2] Bist, Gary, MacKinnon, N. and Murphy, S. “Sequence Diagram Presentation in Technical Documentation.” Proceedings of the 22nd International Conference on Design of Communication (SIGDOC 2004: October 10-13, 2004; Memphis, TN), pp. 128-133. ACM Press: New York, 2004.
[3] Fowler, M. UML Distilled (3rd Ed.) Addison-Wesley, 2004.
[4] Huang, S. and Tilley, S. “Workshop on Graphical Documentation for Programmers: Assessing the Efficacy of UML Diagrams for Program Understanding.” Held in conjunction with The 11th International Workshop on Program Comprehension (IWPC 2003: May 10, 2003; Portland, OR).
[5] MacKinnon, N. and Murphy, S. “Designing UML Diagrams for Technical Documentation.” Proceedings of the 21st Annual International Conference on Design of Communication (SIGDOC 2003: October 12-15, 2003; San Francisco, CA), pp. 105-112. ACM Press: New York, 2003.
[6] Murphy, S.; Tilley, S.; and Huang, S. “4th Workshop on Graphical Documentation: UML Style Guidelines.” Held in conjunction with The 22nd International Conference on Systems Documentation (SIGDOC 2004: October 12, 2004; Memphis, TN).
[7] Object Management Group (OMG). “UML Resource Page”. Online at http://www.uml.org.
[8] 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).
[9] Tilley, S.; Smith, D.; and Thomas, B. “Documentation for Software Engineers: What is Needed to Aid System Understanding?” Held in conjunction with The 19th Annual International Conference on Systems Documentation (SIGDOC 2001: Santa Fe, NM; October 21-24, 2001).
Organizers
Scott Tilley is an Associate Professor in the Department of Computer Sciences at the Florida Institute of Technology. He has a Ph.D. from the University of Victoria. He is the immediate Past Chair of ACM SIGDOC, Chair of
the Steering Committee for the IEEE Web Site Evolution (WSE) series of events, and a member of the SDM-DS and STEP Steering Committees. He is the General Chair for ACM SIGDOC 2005.
Steve Murphy is a media designer at the IBM Toronto Software Laboratory. He leads a team of designers that create graphical support for Information Development writers. He has an honors degree in Fine Arts at the University of Ottawa and a high honors diploma in Illustration at the Sheridan College, Oakville. He is a member of the Program Committee for ACM SIGDOC 2005.
Shihong Huang is an Assistant Professor in the Department of Computer Science & Engineering at Florida Atlantic University. She has a Ph.D. from the University of California, Riverside. She is the Co-PI on a project funded by IBM focused on developing techniques to foster the adoption of UML diagrams for program documentation. She was the Program Chair for ACM SIGDOC 2004.