[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: |
Thu, 08 May 2003 08:34:56 -0400 |
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
- [Gzz-commits] manuscripts/UMLLink short-paper.rst,
Asko Soukka <=
- [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, 2003/05/20
- [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