[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts ./gzigzag.bib UMLLink/SCRATCH UMLLi...
|
From: |
Asko Soukka |
|
Subject: |
[Gzz-commits] manuscripts ./gzigzag.bib UMLLink/SCRATCH UMLLi... |
|
Date: |
Fri, 31 Jan 2003 09:04:05 -0500 |
CVSROOT: /cvsroot/gzz
Module name: manuscripts
Changes by: Asko Soukka <address@hidden> 03/01/31 09:04:05
Modified files:
. : gzigzag.bib
UMLLink : SCRATCH umllink.rst
Log message:
javadoc-paper added
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/gzigzag.bib.diff?tr1=1.12&tr2=1.13&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/SCRATCH.diff?tr1=1.13&tr2=1.14&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.53&tr2=1.54&r1=text&r2=text
Patches:
Index: manuscripts/UMLLink/SCRATCH
diff -u manuscripts/UMLLink/SCRATCH:1.13 manuscripts/UMLLink/SCRATCH:1.14
--- manuscripts/UMLLink/SCRATCH:1.13 Thu Jan 30 11:19:51 2003
+++ manuscripts/UMLLink/SCRATCH Fri Jan 31 09:04:05 2003
@@ -1,4 +1,39 @@
-:Stamp: $Id: SCRATCH,v 1.13 2003/01/30 16:19:51 humppake Exp $
+:Stamp: $Id: SCRATCH,v 1.14 2003/01/31 14:04:05 humppake Exp $
+
+Issues
+------
+
+- How much should we talk about *our* process, how much about
+ processes in general?
+ OTOH, talking more about us makes it more personal but may make it
+ also seem less relevant to others' efforts.
+
+ SUGGESTED RESOLUTION: "Setting of problem" should be about us:
+ describe exactly what docs **we** have. Everything else
+ should be more general, and we should point out that
+ this situation is probably not uncommon.
+
+- why even outdated but well simplified diagram
+ is better than too detailed, automaticly up-to dated
+ and reverse engineered diagram.
+
+ SUGGESTED RESOLUTION: We use UML in our architectural
+ documentation to support our group's intercommunication and
+ describing our project to the open software community. In
+ this use the readability and intelligibility (well abstracted
+ and neatly adjustedt) matters over detailed up-to-dated
+ class spesifications.
+
+- how rational rose links diagrams into code and documentation?
+
+ PARTIAL RESOLUTION: Probably all documentation is primary stored
+ within its own datamodel. The documentation within datamodel could
+ be browsed at least by Rose's hierachical tree menu. Implementation
+ of cross-hierarchical links and browsin along them still unkown.
+ When generating sourcecode, the documentation could be embedded into
+ source as comments. Some user comment didn't like Rose's way of
+ adding extra comments into generated code
+ <http://c2.com/cgi/wiki?RationalRose>
trashbin
--------
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.53
manuscripts/UMLLink/umllink.rst:1.54
--- manuscripts/UMLLink/umllink.rst:1.53 Thu Jan 30 11:19:51 2003
+++ manuscripts/UMLLink/umllink.rst Fri Jan 31 09:04:05 2003
@@ -2,42 +2,7 @@
A free software toolchain for bidirectional linking between UML diagrams and
Javadoc
====================================================================================
-:Stamp: $Id: umllink.rst,v 1.53 2003/01/30 16:19:51 humppake Exp $
-
-Issues
-======
-
-- How much should we talk about *our* process, how much about
- processes in general?
- OTOH, talking more about us makes it more personal but may make it
- also seem less relevant to others' efforts.
-
- SUGGESTED RESOLUTION: "Setting of problem" should be about us:
- describe exactly what docs **we** have. Everything else
- should be more general, and we should point out that
- this situation is probably not uncommon.
-
-- why even outdated but well simplified diagram
- is better than too detailed, automaticly up-to dated
- and reverse engineered diagram.
-
- SUGGESTED RESOLUTION: We use UML in our architectural
- documentation to support our group's intercommunication and
- describing our project to the open software community. In
- this use the readability and intelligibility (well abstracted
- and neatly adjustedt) matters over detailed up-to-dated
- class spesifications.
-
-- how rational rose links diagrams into code and documentation?
-
- PARTIAL RESOLUTION: Probably all documentation is primary stored
- within its own datamodel. The documentation within datamodel could
- be browsed at least by Rose's hierachical tree menu. Implementation
- of cross-hierarchical links and browsin along them still unkown.
- When generating sourcecode, the documentation could be embedded into
- source as comments. Some user comment didn't like Rose's way of
- adding extra comments into generated code
- <http://c2.com/cgi/wiki?RationalRose>
+:Stamp: $Id: umllink.rst,v 1.54 2003/01/31 14:04:05 humppake Exp $
Introduction
============
@@ -47,7 +12,7 @@
industry-standard language for specifying, visualizing, constructing,
and documenting the products in software engineering. Recently, various
approaches have been developed towards unifying software architecture
-design and code, generating the source code from the UML-based
+design and code. This is done by generating the source code from the UML-based
architectural model [#]_ or the reverse-engeneering documentation from
the code [#]_. Nowadays UML seem to be taken in CASE tools even almost
as a visual language, though it's not primarly designed to be a
@@ -63,20 +28,18 @@
booch-jacobson-rumbaugh-uml-reference-manual p.4
Against the trend of unifying the architectural documentation and code
-using UML, we tend still to define the details in the source code and
+fully using UML, we tend still to define the details in the source code and
use UML only for planning and document our software architecture in more
general level. We keep UML as a common language for intercommunication
within our software developer team and within project's all stakeholders.
In this purpose we prefer more well abstracted and comprehensible
human drawn diagrams than exact spesifications matching source code to
-every detail.
-
-[#]_::
+every detail:
"You draw diagrams to visualize a system from different
perspectives, so a diagram is a projection into a system.
For all but the most trivial systems, a diagram represents an elided
- view of the elements that make up a system."
+ view of the elements that make up a system." [#]_
.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
@@ -96,7 +59,7 @@
Parnas and Clements argue that rational software design process is not
generally possible, but acceptable results could be achieved by faking
"the ideal process". Their ideal software design process contains the
-following steps{#]_:
+following steps [#]_:
A) establish and document requirements
B) design and document the module structure
@@ -120,17 +83,17 @@
of mentoring by other group members, before one could be productive for
the project. Sometimes sufficient mentoring could not even be possible,
because members open software projects could be geographically widely
-decentralized. This results the Mythical Man Month effect[#]_: adding a
+decentralized. This results the Mythical Man Month effect [#]_: adding a
new member into software design process could rather delay than speed up
the project:
"Men and months are interchangeable commodities only when a task can be
- partitioned among many workers with no communication."[#]_
+ partitioned among many workers with no communication." [#]_
"The added burden of communication is made up of two
parts, training and intercommunication. Each worker must be trained
in the technology, the goal of the effort, the overall strategy, and
- the plan of work.-- --Intercommunication is worse."[#]_
+ the plan of work.-- --Intercommunication is worse." [#]_
.. [#] brooks-mythical-man-month
@@ -138,11 +101,13 @@
.. [#] brooks-mythical-man-month p.18
+.. [#] brooks-mythical-man-month p.18
+
Eventually, the greater is the amount of programmers or higher turnover within
them, the more important is to have a good documentation. When new programmers
join the project they shouldn't have to depend completely on the old staff for
they information. An up-to-date and rational set of documents available for
-them could ameliorate the Mythical Man Month effect[#]_.
+them could ameliorate the Mythical Man Month effect [#]_.
.. [#] parnas-clements-rational p.255
@@ -184,16 +149,19 @@
java source packages. Besides crosslinking, Javadoc creates indexes and
hierarchical trees as navigational aids for locating individual classes.
-.. [#] http://java.sun.com/j2se/javadoc/
+XXX Little more about Javadoc's history...
-.. [#] Java is a trademark of Sun Microsystems
+.. [#] friendly95javadoc
+
+.. [#] Java is a trademark of Sun Microsystems XXX Friendly, L. had
+ a Java reference
Sun's distribution of Javadoc tools is proprietary, but there exists
also free software (licensed unde GPL) alternatives like doc++ [#]_.
Doc++ is designed to create hypertext documentation also from sourcefile
of other languages (e.g. C, C++, perl).
-.. [#] http://docpp.sourceforge.net/
+.. [#] http://docpp.sourceforge.net/
UML
---
@@ -237,8 +205,8 @@
.. [#] http://www.doxygen.org/
**MetaPhor** [#]_ Project group in University of Jyväskylä have
-looked for ways of using hypertext in CASE tools[#_]. Results of its research
-have been used in **MetaEdit+**[#]_ meta CASE tool developed by MetaCase
+looked for ways of using hypertext in CASE tools [#]_. Results of its research
+have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase
Consulting. MetaEdit+ provides bi-directional linking between all its objects
and interface for reaching linking contexts from diagrams' objects. [ XXX This
should be checked, but metaphor.it.jyu.fi seems to be down :( ]
@@ -251,63 +219,62 @@
Setting of problem
==================
-In our project, as probably in most projects that use Java,
-the software engineering (not user!) documentation is divided into two classes:
-design documentation and Javadoc.
-
-The design documents cover the most important architectural features
-and are written either before coding (for design) or after (for exposition
-of the architecture).
-
-
- - Include PEGs: possibly not-yet accepted or not-yet implemented proposals
- for architectural changes.
-
-
- + creating UML diagrams should be natural part our of design
- (pegboard) and documenting (architecture docs) processes
-
- + as a small group we have too small budget for
- large tools like Rational Rose (also ideological reasons
- to use open source, though open code is always extensible)
-
-
-Javadoc, on the other hand, is
-
- - fully generated documentation from javadoc comments
- of each class and method in the java source code
+In our project, as probably in most projects that use Java programming
language,
+the software development documentation is divided into two classes: the design
+documentation and Javadoc. The design documents cover the most important
+architectural features and are written either before coding (for design) or
after
+(for exposition of the architecture). Javadoc, on the other hand, is detailed
+and fully generated documentation from javadoc comments of each class and
method
+in the java source code.
The two types of documentation are complementary, as demonstrated in the
following table:
-+----------------------------------------+----------------------------------------------+
-| Design docs | Javadoc
|
-+----------------------------------------+----------------------------------------------+
-| |
|
-| - good overall picture. | - easy to find a given class,
|
-| | easy to check all methods
|
-| |
|
-| - little detail, | - detailed
|
-| |
|
-| - may be slightly outdated at | - methods and classes *always* up
to |
-| any particular time. | date (generated from source),
|
-| | doc comments also usually
|
-| |
|
-| - hard to find explanations | - no overall picture of classes'
roles |
-| for a particular class. |
|
-| |
|
-| - UML diagrams |
|
-| |
|
-| - written and organized by humans |
|
-| |
|
-+----------------------------------------+----------------------------------------------+
-
-
-
-Problems with the docs:
-
- + Architectural docs easily left in the dark reaches of the filesystem,
- not used as often as javadocs. - refs about documents left unused because
- hard to find?
++-----------------------------------+------------------------------------+
+| Design docs | Javadoc |
++-----------------------------------+------------------------------------+
+| | |
+| - good overall picture. | - easy to find a given class, |
+| | easy to check all methods |
+| | |
+| - little detail, | - detailed |
+| | |
+| - may be slightly outdated at | - methods and classes *always* up |
+| any particular time. | to date (generated from |
+| | source), doc comments also |
+| | usually |
+| | |
+| - hard to find explanations | - no overall picture of classes' |
+| for a particular class. | roles |
+| | |
+| - UML diagrams | |
+| | |
+| - written and organized by humans | |
+| | |
++-----------------------------------+------------------------------------+
+
+Because Javadoc is fully generated, it is always up to date. Our design
documentation,
+though, is updated manually. Of course, it should be updated regularly during
+every design cycle, but in practise that won't always happen. From our point of
+view it is still ridiculous even talk about generating the design
documentation; the
+design should always be made by human, and if the design documentation is for
human
+reading, it should be also human made. What we could do, is lower the treshold
of
+writing the design documentation.
+
+For detailed documentation we have selected using Javadoc, since even it's
+not open software it's still free and quite easy to use. Also the likeness of
+documentation with most of the other Java based projects is a significant
issue.
+A more difficult issue is to select tools for writing the design documentation
and
+drawing diagrams into it. The solution should be cheap, and as an open software
+project we would prefer other free software. Also the solution should fit well
+to our current working customs.
+
+In addition to the tool selection problem we have to problem of two distinct
+documentation: the human written design documentation and automaticly generated
+detailed Javadoc documentation. During coding the Javadoc documentation is
+often necessary to be, but the architectural design documentation could
+be easily left in the dark reaches of the filesystem. Although, it could also
be
+argued that architectural documents left unused because
+hard to find?
+ hypertext disorientation problem still exists with javadoc
@@ -330,6 +297,16 @@
devices would be those that are spatially based."
[edward-hardman-lost-in-hyperspace, p.123]
+
+ - Include PEGs: possibly not-yet accepted or not-yet implemented proposals
+ for architectural changes.
+
+ + creating UML diagrams should be natural part our of design
+ (pegboard) and documenting (architecture docs) processes
+
+ + as a small group we have too small budget for
+ large tools like Rational Rose (also ideological reasons
+ to use open source, though open code is always extensible)
"Obvious" question: can we increase the overall value by
interconnecting the two?
Index: manuscripts/gzigzag.bib
diff -u manuscripts/gzigzag.bib:1.12 manuscripts/gzigzag.bib:1.13
--- manuscripts/gzigzag.bib:1.12 Tue Jan 28 09:21:39 2003
+++ manuscripts/gzigzag.bib Fri Jan 31 09:04:05 2003
@@ -1303,6 +1303,14 @@
pages = "17--41",
}
address@hidden,
+ author = {Friendly, Lisa},
+ title = {The Design of Distributed Hyperlinked Programming
Documentation},
+ year = {1995},
+ uri = {http://java.sun.com/docs/javadoc-paper.html},
+ note = {Presented at the International Workshop on Hypermedia Design
'95}
+}
+
@comment ------------------------------------------
@comment Peer-to-peer
@comment ------------------------------------------