Designing UML and UML-based diagrams for technical documentation: where are we now?

ABSTRACT

UML diagrams are used to model real-world ideas and help users understand complex programming concepts. Developers and writers need to produce well-formed UML diagrams that can convey these ideas, and that are suitable for publishing in technical documentation. This paper examines the evolution of UML diagrams and tooling, with a focus on practices at the IBM Toronto Software Laboratory. It reviews the findings of two previous papers, which described obstacles to creating UML diagrams for publication and outlined numerous steps to help developers, writers, and graphic designers create useful UML diagrams. It shows how developers at the IBM Toronto Software Laboratory have added new features to existing modeling programs to improve the usability and design functions in IBM's suite of modeling tools. It describes the relative strengths and weaknesses of the two main types of graphics, and illustrates the beneficial impact of the addition of the SVG graphic export function to IBM's tooling. It shows how these functional improvements have resulted in a higher quality of UML diagrams submitted for publication by both technical and non-technical users.

REFERENCES

• 1: Neil MacKinnon , Steve Murphy, Designing UML diagrams for technical documentation, Proceedings of the 21st annual international conference on Documentation, October 12-15, 2003, San Francisco, CA, USA [doi>10.1145/944868.944891]
• 2: Neil MacKinnon , Steve Murphy, Designing UML diagrams for technical documentation: continuing the collaborative approach to publishing class diagrams, Proceedings of the 22nd annual international conference on Design of communication: The engineering of quality documentation, October 10-13, 2004, Memphis, Tennessee, USA [doi>10.1145/1026533.1026565]
• 3: Gary Bist , Neil MacKinnon , Steve Murphy, Sequence diagram presentation in technical documentation, Proceedings of the 22nd annual international conference on Design of communication: The engineering of quality documentation, October 10-13, 2004, Memphis, Tennessee, USA [doi>10.1145/1026533.1026566]
• 4: TheFreeDictionary.com
• 5: TheFreeDictionary.com

INDEX TERMS

Primary Classification:
  H. Information Systems
  H.5 INFORMATION INTERFACES AND PRESENTATION (I.7)
      H.5.2 User Interfaces (D.2.2, H.1.2, I.3.6)
          Subjects: Screen design (e.g., text, graphics, color)

Additional Classification:
  H. Information Systems
  H.5 INFORMATION INTERFACES AND PRESENTATION (I.7)
      H.5.2 User Interfaces (D.2.2, H.1.2, I.3.6)
          Subjects: Training, help, and documentation; Style guides; Theory and methods; Standardization

General Terms:
Design, Documentation, Human Factors, Standardization

Keywords:
UML, UML diagrams, documentation, graphic design, guidelines, human factors, unified modeling language, visualization