design docs and diagrams [was Re: [spinnaker] Announce]

["Randall J. Parr" <RP...@TemporalArts.COM>]

Arved Sandstrom wrote:

> At 10:38 PM 7/8/00 -0700, James Duncan Davidson wrote:
> >on 7/8/00 3:31 PM, Arved Sandstrom at Arved_37@chebucto.ns.ca wrote:
> >
> >> On a very related issue, as "developers" we don't spend most of our time on
> >> code. When we communicate, we communicate with design documents. UML,
> >> IEEE-compliant design descriptions, yada yada.
> >
> >I don't see a lot of UML on Open Source projects. Typically we communicate
> >with code and mail. But that's a personal thing. I can hold a discussion in
> >UML as well as anything -- so what's your design for a NG parser? :)
>
> I don't personally see _any_ UML on open source projects. :-) I wouldn't
> mind seeing some judicious use of the most expressive diagrams, and I plan
> to start sneaking them into FOP, which has some fairly intricate stuff
> happening, and could benefit from them.
>
> This is a completely unrelated tack, but maybe that's something we want to
> encourage - communication of designs with formal modelling notation (not
> getting completely anal, mind you), rather than code. I suppose the main
> problem right now is access to the tools - Visio 2000, or Together/J, or
> Rational Rose, are not cheap. I'm keeping an eye on ArgoUML, though (which
> is under the auspices of the Tigris project), and recommend it to anyone who
> wishes to get a start with UML. There isn't support for everything yet, but
> that's coming.

I heartily agree that many (most) of the open source projects I've worked with
would benefit greatly from requirements and design documentation; most especially
some diagrams. I find that a dozen or so good diagrams often do a better job of
conveying the design and, perhaps more importantly, the design approach or
philosophy, than written documents. More times than I can count I have found
designers, programmers, and end-users are working off a handful of diagrams
they've ripped from the design book.

I also agree that part of the problem is free and/or affordable tools. I have and
use Visio, Rational Rose, Oracle Designer, and others. I too am looking hopefully
towards the next release of ArgoUML and Dia. I would really like to be free of
high-cost, proprietary, MS WINDOWS based tools.

I think there are other factors which do more to discourage the use of these
diagrams in open-source projects. After all, I use Rose, Visio, etc. to produce a
diagram in a standard graphic format (GIF, EPS, ...) which I then use in
documentation or communication.

1) Use of any graphic formats, inclusions, attachments, etc. is very actively
discouraged in most (if not all) of the forums wherein the requirements and design
discussion occur.

2) Few projects seem to give a fraction of the thought to
developing/coordinating/versioning/ documentation source (design or other) as they
to do code source.

It strikes me, documentation and communication of the agreed upon core design
should be one of the most important requirements of an open soure project.

3) Use of diagrams and the like seems to be discouraged even in the design/program
documentation which is produced.

I could blather on (this is a pet peeve of mine) but I won't.

R.Parr
Temporal Arts

Re: design docs and diagrams

[James Duncan Davidson <ja...@eng.sun.com>]

on 7/9/00 4:56 PM, Arved Sandstrom at Arved_37@chebucto.ns.ca wrote:

> This was very interesting, as I have used xfig myself (although not
> recently), and never thought of it. I went and did a Google search and
> located "Universal Modeling Language Library for Xfig"


.....

Note that I've started a design thread on xerces-j-dev... Since you guys are
interested in design, come on in.. :)

.duncan

Re: design docs and diagrams

[Arved Sandstrom <Ar...@chebucto.ns.ca>]

This was very interesting, as I have used xfig myself (although not 
recently), and never thought of it. I went and did a Google search and 
located "Universal Modeling Language Library for Xfig"

http://epb1.lbl.gov/xfig/libraries/UML/index.html

which looks like it might fit the bill. I suspect that this would be our 
closest *UNIX counterpart to Visio.

At 12:55 PM 7/9/00 -0400, Guy Hulbert wrote:
> [ SNIPPAGE ]
>RJP> I think there are other factors which do more to discourage the use of
>RJP> these diagrams in open-source projects. After all, I use Rose, Visio,
>RJP> etc. to produce a diagram in a standard graphic format (GIF, EPS, ...)
>RJP> which I then use in documentation or communication.
>
>Unless you need anything more than templates and pictures (if all you need is
>a "diagram") then Xfig is fine.  I thought that some of these commercial
tools
>also were useful for code generation etc.

I agree; for straight diagrams having templates is sufficient.

The commercial tools offer reverse and/or round-trip engineering, which I 
use with caution. However, this can be extremely useful. I recently imported 
the latest FOP into Together/J, and plan to start uploading the resulting 
class diagrams to FOP CVS. The alternative would have been painful. :-)

One thing that even Visio has, is some built-in UML intelligence. Once 
classes are defined, it is useful to be able to call up a list of available 
methods when drawing a method invocation in a dynamic diagram, for example. 
This helps maintain consistency across diagrams. I suspect that Xfig with 
the UML library probably doesn't do this, so the onus is on the 
illustrator-developer.

>The fig format is pure text, extremely simple and well-documented and a free
>UML tool that used this format would probably not be too hard to create and
>would have the added bonus that the diagrams would be loaded into Xfig for
>editing etc.
>
>	<snip>
>
>----
>Guy Hulbert, Informatics Director	Bioinformatics Supercomputing Centre
>(416) 813-8876				555 University Avenue
>email: guy@bioinfo.sickkids.on.ca	The Hospital for Sick Children
>http:  www.bioinfo.sickkids.on.ca	Toronto, ON, M5G 1X8, CANADA.

Senior Developer
e-plicity.com (www.e-plicity.com)
Halifax, Nova Scotia
"B2B Wireless in Canada's Ocean Playground"

Re: design docs and diagrams

[Guy Hulbert <gu...@bioinfo.sickkids.on.ca>]

On Sun, 9 Jul 2000, Randall J. Parr wrote:

	<snip>

RJP> I heartily agree that many (most) of the open source projects I've worked
RJP> with would benefit greatly from requirements and design documentation;
RJP> most especially some diagrams. I find that a dozen or so good diagrams

	<snip>

RJP> I also agree that part of the problem is free and/or affordable tools. I
RJP> have and use Visio, Rational Rose, Oracle Designer, and others. I too am
RJP> looking hopefully towards the next release of ArgoUML and Dia. I would
RJP> really like to be free of high-cost, proprietary, MS WINDOWS based tools.

Personally, I use xfig for "drawing".

RJP> 
RJP> I think there are other factors which do more to discourage the use of
RJP> these diagrams in open-source projects. After all, I use Rose, Visio,
RJP> etc. to produce a diagram in a standard graphic format (GIF, EPS, ...)
RJP> which I then use in documentation or communication.

Unless you need anything more than templates and pictures (if all you need is
a "diagram") then Xfig is fine.  I thought that some of these commercial tools
also were useful for code generation etc.

The fig format is pure text, extremely simple and well-documented and a free
UML tool that used this format would probably not be too hard to create and
would have the added bonus that the diagrams would be loaded into Xfig for
editing etc.

	<snip>

----
Guy Hulbert, Informatics Director	Bioinformatics Supercomputing Centre
(416) 813-8876				555 University Avenue
email: guy@bioinfo.sickkids.on.ca	The Hospital for Sick Children
http:  www.bioinfo.sickkids.on.ca	Toronto, ON, M5G 1X8, CANADA.