/[gzz]/manuscripts/UMLLink/umllink.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/umllink.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.61 by tuukkah, Tue Feb 11 12:35:08 2003 UTC revision 1.62 by tuukkah, Tue Feb 11 13:52:44 2003 UTC
# Line 101  It should be clear that documentation pl Line 101  It should be clear that documentation pl
101  software design process. Steps listed above should produce documentation,  software design process. Steps listed above should produce documentation,
102  which records requirements or design decisions and could be used  which records requirements or design decisions and could be used
103  as reference manuals throughout the building of the software [#]_. In  as reference manuals throughout the building of the software [#]_. In
104  theory in an open software project new programmers are always free to  theory in an open project new programmers are always free to
105  participate independently. In practice a new programmer could need a lot  participate independently. In practice a new programmer could need a lot
106  of mentoring by other group members, before one could be productive for  of mentoring by other group members, before one could be productive for
107  the project. Sometimes sufficient mentoring could not even be possible,  the project. Sometimes sufficient mentoring could not even be possible,
108  because members open software projects could be geographically widely  because members of such a projects could be geographically widely
109  decentralized. This results the Mythical Man Month effect [#]_: adding a  scattered. This results in the Mythical Man Month effect [#]_: adding a
110  new member into software design process could rather delay than speed up  new member into software design process could rather delay than speed up
111  the project:  the project:
112    
# Line 126  the project: Line 126  the project:
126    
127  .. [#] brooks-mythical-man-month p.18  .. [#] brooks-mythical-man-month p.18
128    
129  Eventually, the greater is the amount of programmers or higher turnover within  Eventually, the greater is the amount of programmers or higher the turnover
130  them, the more important is to have a good documentation. When new programmers  within them, the more important it is to have a good documentation.
131    When new programmers
132  join the project they shouldn't have to depend completely on the old staff for  join the project they shouldn't have to depend completely on the old staff for
133  they information. An up-to-date and rational set of documents available for  their information. An up-to-date and rational set of documents available for
134  them could ameliorate the Mythical Man Month effect [#]_.  them could ameliorate the Mythical Man Month effect [#]_.
135    
136  .. [#] parnas-clements-rational p.255  .. [#] parnas-clements-rational p.255
137    
138  Because our group is doing experimental research, we need a flexible  Because our group is doing experimental research, we need a flexible
139  model for software development process. From the classical software  model for software development process. From the classical software
140  development process models, our one reminds most Boehm's spiral model  development process models, ours reminds most of Boehm's spiral model
141  of software development and enhancement [#]_. The spiral model  of software development and enhancement [#]_. The spiral model
142  is a cyclic and repeative model, where every cycle has the following  is cyclic and repetitive, and every cycle has the following
143  phases [#]_:  phases [#]_:
144    
145   * determining objectives, alternatives, constraints   * determining objectives, alternatives, constraints
# Line 155  phases [#]_: Line 156  phases [#]_:
156    
157  .. [#] beck99xp  .. [#] beck99xp
158    
159  The nature of our software development process affects also strongly to  The nature of our software development process affects also strongly
160  our documentation needs. As we proceed by prototyping and enhancing our  our documentation needs. As we proceed by prototyping and enhancing our
161  software step by step, also our documentation should be updated in every  software step by step, also our documentation should be updated in every
162  cycle. Because the detailed implementation is in continual change, we prefer  cycle. Because the detailed implementation is in continual change, we prefer
163  to weight our documentation to more constant and general architectural  to emphasis the more constant and general architectural
164  documentation. Of course more detailed up-to-date documentation could be  documentation. Of course, more detailed up-to-date documentation could be
165  generated from the current source for those members, who are working with  generated from the current source for those members who are working with
166  particular details. Though, in general documentation rapidly changing details  particular details. Though, in general documentation rapidly changing details
167  would be irrelevant and confusing. Since currently the main purpose for our  would be irrelevant and confusing. Since currently the main purpose for our
168  documentation is to help intercommunication within our group, we believe manually  documentation is to help intercommunication within our group, we believe manually
169  made human abstracted documentation serving our purposes best.  made human abstracted documentation serves our purposes best.
170        
171  Javadoc  Javadoc
172  -------  -------
173    
174  **Javadoc** [#]_ is a hypertext documentation tool developed by Sun  **Javadoc** [#]_ is a hypertext documentation tool developed by Sun
175  Microsystems and delivered with Sun's Java distribution packages [#]_.  Microsystems and delivered with Sun's Java Development Kit [#]_.
176  Javadoc generates detailed and well crosslinked hypertext documentation  Javadoc generates detailed and massively crosslinked hypertext documentation
177  analyzing class hierarchies and including documentation comments from  after analyzing class hierarchies and references, and includes documentation
178  java source packages. Besides crosslinking, Javadoc creates indexes and  comments from
179  hierarchical trees as navigational aids for locating individual classes.  java source code. Besides crosslinking, Javadoc creates alphabetical indexes
180    and hierarchical trees to aid navigation into individual classes.
181    
182  ``XXX Little more about Javadoc's history...``  ``XXX Little more about Javadoc's history...``
183    
# Line 184  hierarchical trees as navigational aids Line 186  hierarchical trees as navigational aids
186  .. [#] Java is a trademark of Sun Microsystems XXX Friendly, L. had  .. [#] Java is a trademark of Sun Microsystems XXX Friendly, L. had
187         a Java reference         a Java reference
188    
189  Sun's distribution of Javadoc tools is proprietary, but there exists  Sun's distribution of Javadoc tools is proprietary, but alternatives such as
190  also free software (licensed unde GPL) alternatives like doc++ [#]_.  doc++ [#]_ exist as free software (licensed under GPL).
191  Doc++ is designed to create hypertext documentation also from sourcefile  Doc++ is designed to create hypertext documentation from other languages
192  of other languages (e.g. C, C++, perl).  (e.g. C, C++, perl), in addition to Java.
193    
194  .. [#] http://docpp.sourceforge.net/  .. [#] http://docpp.sourceforge.net/
195    
# Line 196  UML Line 198  UML
198    
199  **Rational Rose** [#]_ is quite honored UML design tool. It provides a  **Rational Rose** [#]_ is quite honored UML design tool. It provides a
200  direct manipulation interface for drawing different kinds of UML diagrams  direct manipulation interface for drawing different kinds of UML diagrams
201  into it's data model, which is also supported by other products of Rational  into its database, which is also supported by other products of Rational
202  Software Corporations Rational product family. In addition of drawing  Software Corporation's Rational product family. In addition to drawing
203  diagrams from scratch, it allows reverse engineering diagrams from  diagrams from scratch, it allows reverse engineering diagrams from
204  code [#]_.  code [#]_.
205    
206  Rational Rose could be used with **Rational Soda** [#]_ for creating more  Rational Rose could be used with **Rational Soda** [#]_ to create more
207  general architecture documentation. Soda is WYSIWYG (What You See Is What  general architecture documentation. Soda is WYSIWYG (What You See Is What
208  You Get) documentation writing tool which allows including diagrams and  You Get) documentation writing tool, which allows including diagrams and
209  documentation data from Rational Rose's data model within the written  documentation data from Rational Rose's database to the written
210  documentation. The both, Rational Rose and Rational Soda, are proprietary  documentation. Both Rational Rose and Rational Soda are proprietary
211  software and quite expensive for use of small research groups. Problems of  software and quite expensive for use of small research groups. Problems of
212  direct manipulation and WYSIWYG interfaces are discussed later.  direct manipulation and WYSIWYG interfaces are discussed later.
213    
# Line 222  and it has a plugin interface for new dr Line 224  and it has a plugin interface for new dr
224    
225  .. [#] http://www.lysator.liu.se/~alla/dia/  .. [#] http://www.lysator.liu.se/~alla/dia/
226    
227  **Doxygen** [#]_ is an another Javadoc-like documentation tool, which generates  **Doxygen** [#]_ is another Javadoc-like documentation tool, which generates
228  hypertext documentation from source code of good variety of different languges.  hypertext documentation from source code of good variety of different languges.
229  An intresting feature in Doxygen is that it can also generates and embed  An intresting feature in Doxygen is that it can also generate and embed
230  UML diagrams representing software's class and inheritance hierarchies into  into class documentation UML diagrams representing software's class and
231  class documentation. Also the focused class is higlighted in diagrams on its  inheritance hierarchies.
232  documentation pages. Another enhancement for javadoc in Doxygen is that  Also the focused class is higlighted in diagrams on its
233  it creates dynamic shrinkable treeview for class hierarchy.  documentation pages. Another enhancement to javadoc in Doxygen is that
234    it creates a dynamic shrinkable treeview for class hierarchy.
235    
236  .. [#] http://www.doxygen.org/  .. [#] http://www.doxygen.org/
237    
238  **MetaPhor** [#]_ Project group in University of Jyväskylä have  **MetaPhor** [#]_ Project in University of Jyväskylä have
239  looked for ways of using hypertext in CASE tools [#]_. Results of its research  looked for ways of using hypertext in CASE tools [#]_. Results of its research
240  have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase  have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase
241  Consulting. MetaEdit+ provides bi-directional linking between all its objects  Consulting. MetaEdit+ provides bi-directional linking between all its objects
242  and interface for reaching linking contexts from diagrams' objects.  and an interface for reaching linking contexts from diagrams' objects.
243    
244  :   XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ]  :   XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ]
245    
# Line 288  every design cycle, but in practise that Line 291  every design cycle, but in practise that
291  view it is still ridiculous even talk about generating the design documentation; the  view it is still ridiculous even talk about generating the design documentation; the
292  design should always be made by human, and if the design documentation is for human  design should always be made by human, and if the design documentation is for human
293  reading, it should be also human made. What we could do, is lower the treshold of  reading, it should be also human made. What we could do, is lower the treshold of
294  writing the design documentation.  getting into writing the design documentation.
295    
296  For detailed documentation we have selected using Javadoc, since even it's  For detailed documentation we have decided to use Javadoc, since even though
297  not open software it's still free and quite easy to use. Also the likeness of  it's
298    not free software it's still usable for free and quite easy to use. Also the likeness of
299  documentation with most of the other Java based projects is a significant issue.  documentation with most of the other Java based projects is a significant issue.
300  A more difficult issue is to select tools for writing the design documentation and  A more difficult issue is to select tools for writing the design documentation and
301  drawing diagrams into it. The solution should be cheap, and as an open software  drawing diagrams into it. The solution should be cheap, and as a free software
302  project we would prefer other free software. Also the solution should fit well  project we would prefer other free software. Also the solution should fit well
303  to our current working customs.  to our current working customs.
304    
305  In addition to the tool selection problem we have to problem of two distinct  In addition to the tool selection problem we have to problem of two distinct
306  documentation: the human written design documentation and automaticly generated  pieces of documentation: the human written design documentation and the
307    automatically generated
308  detailed Javadoc documentation. During coding the Javadoc documentation is  detailed Javadoc documentation. During coding the Javadoc documentation is
309  often necessary, but the architectural design documentation could be easily left  often necessary, but the architectural design documentation could be easily left
310  in the dark reaches of the filesystem. It could be argued that architectural  in the dark reaches of the filesystem. It could be argued that the reason for
311  documents are left unused, because relevant parts linked to ongoing work are  architectural
312  hard to find. The two distinct documentation (javadoc and design documentation)  documents being left unused is that relevant parts linked to ongoing work are
313  cannot seen as whole. Therefore we should make them work as a whole.  hard to find. The distinct pieces (javadoc and design documentation)
314    cannot seen as a whole. Therefore we should make them work as a whole.
315    
316  "Obvious" question: can we increase the overall value by interconnecting the  "Obvious" question: can we increase the overall value by interconnecting the
317  two distinct documentations?  two distinct pieces of documentation?
318    
319  When looking at a design document, jumping to the javadocs to get the details  When looking at a design document, jumping to the javadocs to get the details
320  would be useful, and when looking at a Javadoc, it would be useful  would be useful, and when looking at a Javadoc, it would be useful
321  to be able to see if any design documents refer to that class.  to be able to see if any design documents refer to that class.
322  We believe that the architecture document will be read more, after it's  We believe that the architecture document will be read more, after it's
323  it's easily reachable from relevant parts of Javadoc.  easily reachable from relevant parts of Javadoc.
324  This is the starting point for the toolchain developed in this article.  This is the starting point for the toolchain developed in this article.
325    
326    

Legend:
Removed from v.1.61  
changed lines
  Added in v.1.62

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26