/[gzz]/manuscripts/UMLLink/short-paper.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/short-paper.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.12 by tjl, Tue May 20 19:18:25 2003 UTC revision 1.13 by tjl, Tue May 20 19:29:51 2003 UTC
# Line 77  What is often missing is the connections Line 77  What is often missing is the connections
77  the design documentation and the embedded documentation.  the design documentation and the embedded documentation.
78  This can be daunting to a newcomer; consider the javadoc  This can be daunting to a newcomer; consider the javadoc
79  for the interface ``java.security.PublicKey`` in Sun's  for the interface ``java.security.PublicKey`` in Sun's
80  Java2 SDK 1.4.1 at  Java2 SDK 1.4.1
81  ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.  XXXREF.
 XXXREF  
82  While the class is easy to find through the package and class lists  While the class is easy to find through the package and class lists
83  when looking for a class to represent cryptographical public keys,  when looking for a class to represent cryptographical public keys,
84  the javadoc is not terribly useful: there is no information  the javadoc is not terribly useful: there is no information
85  there on how one may create objects that implement this interface.  there on how one may create objects that implement this interface.
86  The only way to find this out is to click on the ``Use`` link  The only way to find this out is to click on the ``Use`` link
87  which lists all the occurrences of this class as method  which lists all the occurrences of this class as method
88  return values or parameters.  return values or parameters, without much contextual information
89    about the importance of the methods.
90  However, what would really help would be a link to the design  However, what would really help would be a link to the design
91  documentation, even just a UML diagram of what the intended  documentation, even just a diagram of what the intended
92  uses or lifespans of classes implementing this interface  uses or lifespans of classes implementing this interface
93  are and how one creates them.  are and how one creates them.
94    These diagrams certainly exist for all properly managed
95    medium-to-large scale software projects --- the problem is getting
96    them to where it matters.
97    
98  In this article, we discuss Navidoc: a system that, given design  .. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
99    
100    In this article, we introduce Navidoc: a system that, given design
101  documentation with marked-up UML diagrams, inserts the UML  documentation with marked-up UML diagrams, inserts the UML
102  diagrams into the classes' javadocs to function as spatial menus.  diagrams into the classes' javadocs to function as spatial menus.
103    
# Line 145  describe software architectures and cons Line 150  describe software architectures and cons
150  [booch-jacobson-rumbaugh98uml-user-guide]_. As a standard it is a  [booch-jacobson-rumbaugh98uml-user-guide]_. As a standard it is a
151  natural part of software design documentation, because it functions as  natural part of software design documentation, because it functions as
152  a common language for communication within a software development  a common language for communication within a software development
153  team. Because UML diagrams should be made anyway, it is good start to  team. Each UML diagram is meant to expose a particular aspect
154  think about using them also for navigation.  of the design.
155    Therefore
156  The usability of hypertext-based documentation is said to might suffer  a single program element may appear on several distinct diagrams,
157  from user's disorientation: the tendency to lose one's sense of  that
158  location and direction in a nonlinear documents  together create a multicontext view for the element.
159  [conklin87hypertext-onpage-38-40]_. It is also said that the most  
160  appropriate types of navigation devices should be based on spatiality  
161  to allow users to develop a cognitive map of the data structure before  ..  Because UML diagrams should be made anyway, it is good start to
162  moving within it [edwards-hardman89lost-in-hyperspace-onpage-123]_.      think about using them also for navigation.
163        (said in intro now)
164    
165    ..  The usability of hypertext-based documentation may suffer
166        from user's disorientation: the tendency to lose one's sense of
167        location and direction in a nonlinear documents
168        [conklin87hypertext-onpage-38-40]_. It is also said that the most
169        appropriate types of navigation devices should be based on spatiality
170        to allow users to develop a cognitive map of the data structure before
171        moving within it [edwards-hardman89lost-in-hyperspace-onpage-123]_.
172    
173  Besides UML diagrams are spatial, they are encouraged to be  Besides UML diagrams are spatial, they are encouraged to be
174  complementary [booch-jacobson-rumbaugh98uml-user-guide-10]_. Therefore  complementary
 a single element may appear in several distinct diagrams, that all  
 together create a multicontext view for the element. ...  
175    
176  .. multicontext views versus traditional hierarchical documentation  .. multicontext views versus traditional hierarchical documentation
177    
# Line 171  together create a multicontext view for Line 183  together create a multicontext view for
183        for documentation navigation, but it's still much better than nothing        for documentation navigation, but it's still much better than nothing
184    
185  - why UML-diagrams would work as menus  - why UML-diagrams would work as menus
186    
187    * UMLs human made abstraction of the system containing    * UMLs human made abstraction of the system containing
188      all the most relevant parts      all the most relevant parts
189    
190    * don't link to everywhere, but to the most essential places    * don't link to everywhere, but to the most essential places
191    
192    * UMLs are already natural part of the design documentation    * UMLs are already natural part of the design documentation
193      and thus, familiar to development grew reading documentation      and thus, familiar to development grew reading documentation
194    

Legend:
Removed from v.1.12  
changed lines
  Added in v.1.13

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26