[Gzz-commits] manuscripts/UMLLink short-paper.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/05/19 10:01:59

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        today

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/short-paper.rst.diff?tr1=1.5&tr2=1.6&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.5 
manuscripts/UMLLink/short-paper.rst:1.6
--- manuscripts/UMLLink/short-paper.rst:1.5     Thu May  8 08:34:56 2003
+++ manuscripts/UMLLink/short-paper.rst Mon May 19 10:01:59 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.5 2003/05/08 12:34:56 humppake Exp $
+.. $Id: short-paper.rst,v 1.6 2003/05/19 14:01:59 humppake Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -60,11 +60,11 @@
 
 There exist plenty of documentation tools to generate well navigable
 documentations from program code source files. Altough, many of them
-are designed to work with different programming languages, there may
-exist conventions to use specific documentation tool with specific
+are designed to work with many different programming languages, there
+may exist conventions to use specific documentation tool with specific
 programming language (like Javadoc with Java). When a yet another tool
 is used to write the design documentation, linking all documentation
-together by hand would be tedious and error-prone. 
+together by hand would be tedious and error-prone.
 
 .. - short description about problem:
      * programming language specific tools like javadoc do generate 
@@ -84,49 +84,51 @@
 Our solution to link distinct software development documentations
 together is to base it on UML diagrams which are drawn on design
 documentation to abstract the system under development. We believe
-that advantages of using UML diagrams navigational aids clearly beat
+that advantages of using UML diagrams as navigational aids clearly beat
 the minor additional work that is needed.
 
 .. It could be that UML diagrams won't be optimal for navigation of hypertext 
and
    they won't cover the whole documentation. 
 
-- resolving:
-  * connecting distinct fragments together using design
-    documentation's UML diagrams
-  * bidirectional linking
-  * several context views (different UML diagrams), multimenu
-    * spatial navigation (within the diagram)
-
-Creation of navigational UML diagrams
-=====================================
-
-- why UML
-  * UML is de facto standard for describing software architecture
-    - probably not best, but good enough and widely used
-  * diagrams must be drawn anyway, if they already exists, why not use them
-  * we do not claim that UML work as the best possible diagrams
-    for documentation navigation, but it's still much better than nothing
-
-.. In this article we focus on the more conventional use of UML to plan
-   and document software architecture on a general level.  UML can
-   function as a common language for communication within a software
-   development team, and for this purpose we prefer human-drawn
-   (non-autogenerated) diagrams that show the semantically meaningful
-   features at the right level of abstraction:
-
-.. The usability of xhypertext-based documentation may suffer from user's
-   disorientation: the tendency to lose one's sense of location and
-   direction in a nonlinear documents
-   [conklin87hypertext-onpage-38-40]_. This means that users don't know
-   where they are in the documentation network or how to get to some
-   other place that they know to exist in the network.
-
-.. Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that
-   the most appropriate types of navigation devices would be based on
-   spatiality. They conlude that users should be allowed to develop a
-   cognitive map of one view of the data structure before being given the
-   opinion of navigating through the data some other way
-   [edwards-hardman89lost-in-hyperspace-onpage-123]_.
+.. - resolving:
+    * connecting distinct fragments together using design
+      documentation's UML diagrams
+    * bidirectional linking
+    * several context views (different UML diagrams), multimenu
+      * spatial navigation (within the diagram)
+
+UML diagrams as spatial menus
+=============================
+
+The Unified Modeling Language (UML) is the standard way to visually
+describe software architectures and constructs in diagrams
+[booch-jacobson-rumbaugh98uml-user-guide]_. As a standard it is a
+natural part of software design documentation, because it functions as
+a common language for communication within a software development
+team. Because UML diagrams should be made anyway, it is good start to
+think about using them also for navigation.
+
+The usability of hypertext-based documentation is said to might suffer
+from user's disorientation: the tendency to lose one's sense of
+location and direction in a nonlinear documents
+[conklin87hypertext-onpage-38-40]_. It is also said that the most
+appropriate types of navigation devices should be based on spatiality
+to allow users to develop a cognitive map of the data structure before
+moving within it [edwards-hardman89lost-in-hyperspace-onpage-123]_.
+
+Besides UML diagrams are spatial, they are encouraged to be
+complementary [booch-jacobson-rumbaugh98uml-user-guide-10]_. Therefore
+a single element may appear in several distinct diagrams, that all
+together create a multicontext view for the element. ...
+
+.. multicontext views versus traditional hierarchical documentation
+ 
+.. - why UML
+    * UML is de facto standard for describing software architecture
+      - probably not best, but good enough and widely used
+    * diagrams must be drawn anyway, if they already exists, why not use them
+    * we do not claim that UML work as the best possible diagrams
+      for documentation navigation, but it's still much better than nothing
 
 - why UML-diagrams would work as menus
   * UMLs human made abstraction of the system containing
@@ -135,6 +137,23 @@
   * UMLs are already natural part of the design documentation
     and thus, familiar to development grew reading documentation
 
+Making it easy
+==============
+
+It is not a new idea to use UML diagrams in documentation
+navigation. There already exists Javadoc like documentation generation
+tools, which generate automaticly classdiagrams from program source
+code to help navigation in generated documentation. Doxygen
+[heesch03doxygen]_ ,for example, generates diagrams of class
+inheritance tree for that purpose.
+
+Of course, generated documentation may give well detailed information
+from the current implementation, but the design documentation should
+also cover the future and be rather well abstracted than well
+detailed. Therefore, we want to avoid being bloated by a large amount
+of too detailed diagrams (meanless for us) and prefer fully human
+created diagrams in our design documentation.
+                                                            
 - how are UMLs embedded into documentation
   * using lexical UML language
 
@@ -143,8 +162,8 @@
   * describing is fast
   * setting layout may be more 
 
-Embedding diagrams into HTML
-============================
+.. Embedding diagrams into HTML
+   ============================
 
 Javadoc [friendly95javadoc]_ is a detailed and fully generated
 documentation from javadoc comments of each class and method in the