[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink short-paper.rst
From: |
Tuomas J. Lukka |
Subject: |
[Gzz-commits] manuscripts/UMLLink short-paper.rst |
Date: |
Tue, 20 May 2003 15:29:51 -0400 |
CVSROOT: /cvsroot/gzz
Module name: manuscripts
Changes by: Tuomas J. Lukka <address@hidden> 03/05/20 15:29:51
Modified files:
UMLLink : short-paper.rst
Log message:
shorten,edit
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/short-paper.rst.diff?tr1=1.12&tr2=1.13&r1=text&r2=text
Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.12
manuscripts/UMLLink/short-paper.rst:1.13
--- manuscripts/UMLLink/short-paper.rst:1.12 Tue May 20 15:18:25 2003
+++ manuscripts/UMLLink/short-paper.rst Tue May 20 15:29:51 2003
@@ -2,7 +2,7 @@
Bridging Javadoc and design documentation via UML diagram image maps
====================================================================
-.. $Id: short-paper.rst,v 1.12 2003/05/20 19:18:25 tjl Exp $
+.. $Id: short-paper.rst,v 1.13 2003/05/20 19:29:51 tjl Exp $
.. short paper == 2 pages, deadline the end of May
@@ -77,22 +77,27 @@
the design documentation and the embedded documentation.
This can be daunting to a newcomer; consider the javadoc
for the interface ``java.security.PublicKey`` in Sun's
-Java2 SDK 1.4.1 at
-``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
-XXXREF
+Java2 SDK 1.4.1
+XXXREF.
While the class is easy to find through the package and class lists
when looking for a class to represent cryptographical public keys,
the javadoc is not terribly useful: there is no information
there on how one may create objects that implement this interface.
The only way to find this out is to click on the ``Use`` link
which lists all the occurrences of this class as method
-return values or parameters.
+return values or parameters, without much contextual information
+about the importance of the methods.
However, what would really help would be a link to the design
-documentation, even just a UML diagram of what the intended
+documentation, even just a diagram of what the intended
uses or lifespans of classes implementing this interface
-are and how one creates them.
+are and how one creates them.
+These diagrams certainly exist for all properly managed
+medium-to-large scale software projects --- the problem is getting
+them to where it matters.
-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``.
+
+In this article, we introduce Navidoc: a system that, given design
documentation with marked-up UML diagrams, inserts the UML
diagrams into the classes' javadocs to function as spatial menus.
@@ -145,21 +150,28 @@
[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]_.
+team. Each UML diagram is meant to expose a particular aspect
+of the design.
+Therefore
+a single program element may appear on several distinct diagrams,
+that
+together create a multicontext view for the element.
+
+
+.. Because UML diagrams should be made anyway, it is good start to
+ think about using them also for navigation.
+ (said in intro now)
+
+.. The usability of hypertext-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]_. 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. ...
+complementary
.. multicontext views versus traditional hierarchical documentation
@@ -171,9 +183,12 @@
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
all the most relevant parts
+
* don't link to everywhere, but to the most essential places
+
* UMLs are already natural part of the design documentation
and thus, familiar to development grew reading documentation
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/08
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/19
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst,
Tuomas J. Lukka <=
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21