[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink short-paper.rst
From: |
Asko Soukka |
Subject: |
[Gzz-commits] manuscripts/UMLLink short-paper.rst |
Date: |
Wed, 30 Apr 2003 10:20:41 -0400 |
CVSROOT: /cvsroot/gzz
Module name: manuscripts
Changes by: Asko Soukka <address@hidden> 03/04/30 10:20:41
Modified files:
UMLLink : short-paper.rst
Log message:
some
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/short-paper.rst.diff?tr1=1.3&tr2=1.4&r1=text&r2=text
Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.3
manuscripts/UMLLink/short-paper.rst:1.4
--- manuscripts/UMLLink/short-paper.rst:1.3 Thu Apr 24 07:53:20 2003
+++ manuscripts/UMLLink/short-paper.rst Wed Apr 30 10:20:41 2003
@@ -2,7 +2,7 @@
Bridging Javadoc and design documentation via UML diagram image maps
====================================================================
-.. $Id: short-paper.rst,v 1.3 2003/04/24 11:53:20 humppake Exp $
+.. $Id: short-paper.rst,v 1.4 2003/04/30 14:20:41 humppake Exp $
.. short paper == 2 pages, deadline the end of May
@@ -37,16 +37,43 @@
=========
- short description about problem:
- * programming language specific tools generate
- well linked but distinct documentations from source code
- * above all is human written abstraction to the system
+ * 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.
- 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)
+
+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]_.
- why UML
* UML is de facto standard for describing software architecture
@@ -55,6 +82,25 @@
* 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.
+
- why UML-diagrams would work as menus
* UMLs human made abstraction of the system containing
all the most relevant parts
@@ -96,3 +142,5 @@
- future
* fenfire
+
+.. bibliography:: gzigzag