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

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/05/08 08:34:56

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        work

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.4 
manuscripts/UMLLink/short-paper.rst:1.5
--- manuscripts/UMLLink/short-paper.rst:1.4     Wed Apr 30 10:20:41 2003
+++ manuscripts/UMLLink/short-paper.rst Thu May  8 08:34:56 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.4 2003/04/30 14:20:41 humppake Exp $
+.. $Id: short-paper.rst,v 1.5 2003/05/08 12:34:56 humppake Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -33,27 +33,62 @@
    - [humppake] couldn't find yet
 
 
-Sketching
-=========
+Abstract
+========
 
-- short description about problem:
-  * programming language specific tools like javadoc do generate 
-    well navigable documentations from source code
-  * above them is a human written abstraction to the system
-    as whole - the design documentation
-  * how to make these documentation fragments interconnected
-    with each other with minimum additional work
- 
-  Should be searched previous papers, which have research
-  quostions alike. Check at first the keywords given by referees
-  of UMLLink article.
-
-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 document
-[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.
+We present a navigational aid for documentation used in software
+development. Based on using readily-authored UML diagrams as multi-ended 
+links, we hypertexturally connect two distinct areas of documentation: design
+documents and javadoc program code documentation. 
+
+.. Connecting the distinct areas is essential because it could help new
+   developers in getting productive and supports development processes
+   where both design and implementation change continuously.
+
+Introduction
+============
+
+Software projects manage a large base of evolving documentation, which
+is inter-related on many levels. Design documentation gives
+architectural views on a more general level, while the program code
+source files contain minute interface specifications and often also
+embedded documentation giving details on how the interfaces should be
+used.
+
+.. Since these parts of documentation are semantically dependent
+   they should be interlinked together.
+
+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
+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. 
+
+.. - short description about problem:
+     * programming language specific tools like javadoc do generate 
+       well navigable documentations from source code
+     * above them is a human written abstraction to the system
+       as whole - the design documentation
+     * how to make these documentation fragments interconnected+
+       with each other with minimum additional work
+
+   Should be searched previous papers, which have research
+   quostions alike. Check at first the keywords given by referees
+   of UMLLink article.
+
+Connecting the distinct areas is essential because it could help new
+developers in getting productive and supports development processes
+where both design and implementation change continuously.
+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
+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
@@ -62,18 +97,8 @@
   * several context views (different UML diagrams), multimenu
     * spatial navigation (within the diagram)
 
-Javadoc [friendly95javadoc]_ is a detailed and fully generated
-documentation from javadoc comments of each class and method in the
-Java source code.
-
-Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that
-the most appropriate types of navigation devices would be based on
-spatiality. According to their research, individuals appear to be
-attempting to create cognitive representations of hypertext structures
-in the form of a survey-type map. 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]_.
+Creation of navigational UML diagrams
+=====================================
 
 - why UML
   * UML is de facto standard for describing software architecture
@@ -82,24 +107,26 @@
   * 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 distinct pieces (Javadoc and the design documentation) cannot seen as a 
-whole. The obvious question, then, is: can we increase the overall value by 
-hyperlinking the two distinct pieces of documentation? 
-
-When looking at a design document, jumping to the Javadocs to get the
-details would be useful, and when looking at a Javadoc, it would be
-most useful to be able to see if any design documents discuss that class
-or package.
-We believe that the design documentation would be read more if 
-made easily reachable from relevant parts of Javadoc. 
+.. 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]_.
 
 - why UML-diagrams would work as menus
   * UMLs human made abstraction of the system containing
@@ -116,6 +143,13 @@
   * describing is fast
   * setting layout may be more 
 
+Embedding diagrams into HTML
+============================
+
+Javadoc [friendly95javadoc]_ is a detailed and fully generated
+documentation from javadoc comments of each class and method in the
+Java source code.
+
 - why html
   * platform and software independent documentation
   * could be distributed in WWW, intranets etc... as it is
@@ -134,13 +168,21 @@
   * created under gzz 
   * separated as navidoc
 
+Usage
+=====
+
 - does it really work
   * WWW statistics from himalia, some comparison
     between pages containing UML and pages that 
     does not contain
   * what does the previous prove?
 
-- future
-  * fenfire
+Conclusion
+==========
+
+.. - future
+    * fenfire
+
+
 
 .. bibliography:: gzigzag