Re: documenting Lenya system architecture, diagrams and (maybe) UML (Was: Re: [Lenya Wiki] Update of "DocumentCreationAPI" by WolfgangKaltz)

[Andreas Hartmann <an...@apache.org>]

J. Wolfgang Kaltz wrote:
> Gregor J. Rothfuss schrieb:
> 
>> J. Wolfgang Kaltz wrote:
>>
>>> I'm curious whether you believe UML diagrams can be helpful for
>>> - documenting Lenya internals (and if so, do we want to do that)
>>> - discussing architectural changes
>>
>>
>>
>> yes as long as they are kept current, which is easily possible with 
>> eclipse UML plugins. maybe we can have a build target for these?
>>
>> the problem i have found is that a UML diagram of all of lenya is 
>> rather large, and needs to be decomposed to be useful.
> 
> 
> Frankly, I don't see how any diagram automatically generated from the 
> sources can be helpful. The only thing that can be generated is the 
> class diagram of all of Lenya, and like you said, there are simply too 
> many classes; plus usually you want to explain a certain part, not all 
> at once.

I agree, auto-generated diagrams don't seem to be very helpful without
tweaking the class and association selection and the output.
Creating a diagram of comprehensible size from scratch won't take
much more time.

A while ago I posted some hand-drawn diagrams (digitalized with
a digicam), IMO that's the quickest method and quite helpful.
I could never get used to UML tools - they are more complicated
to use than a pencil and don't add much benefit apart from generating
some mock code.


> Admittedly, navigating through the Javadocs one can fairly quickly get 
> an idea of the class hierarchy. What is more difficult to grasp is how & 
> when instances are created, and how they interact with each other. I'm 
> hoping sequence diagrams can be useful here.
> 
> For the bigger picture, something like component diagrams might be useful.

+1

-- Andreas

> <philosophy>
> To be honest, I haven't been drawing many diagrams since I started 
> working on Web apps, 1999. Before that, I was drawing database designs 
> before actually writing SQL code. The Web has seemed to me a bit like 
> the wild west; code (shoot) first and think (judge) later. Since Web 
> apps are often going new ways, it is often not possible to design the 
> app in advance. But I am sure that it will increasingly be a customer 
> requirement that Web apps too have some form of serious system 
> documentation, after they have been developed. Remember that article on 
> the state of open-source CMS a few months ago ? I understood the 
> conclusion as being this: php-based CMS are more advanced in terms of 
> features; Java-based CMS have the advantage of a sounder system 
> architecture and thus are a better base for future developments. But to 
> prove this (and have a sales argument), that system architecture needs 
> to be documented.
> </philosophy>
> 
> 
>>> (...)
>>> Another problem is that it is not only Java classes that are 
>>> involved, but also Cocoon configuration files (sitemaps), Lenya 
>>> configuration files, flowscript, ... I don't know how these would fit 
>>> in in UML diagrams.
>>
>>
>>
>> that is true, and is a concern for eclipe lepido, the upcoming cooon 
>> editor for eclipse which attempts to have a metamodel of cocoon that 
>> can describe not just java code, but also these config files.
> 
> 
> That indeed looks like an important project for the Cocoon-based 
> development community. The focus seems to be on development tools. Are 
> you aware of efforts to come up with a notation to document Cocoon-based 
> apps ? Meaning, a common notation (tool-free) for things like sitemaps, 
> pipelines, maybe schemes, ...
> 
> 
> -- 
> Wolfgang


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org