Higher level project documentation, Was: Re: Other 2.6.2 changes

[Florian Holeczek <fl...@holeczek.de>]

Hi there,

> Yes, I can certainly see what the issue here is - we are lacking
> some "big picture" documentation. The Javadocs are great if you know
> what you are doing, but if you don't know what the feature is and
> how it fits in the JSPWiki architecture, it's not that clear. HOWTOs
> and tutorials would be great, too.

that's the essence!

Aren't there any tools which could analyze a code base and generate a
project map / graphical class overview with dependencies a.s.o.?

> However, I can't stress enough the fact that this is a collaborative
> project, and as such, we *need* more people who can write concise  
> documentation, howtos, architecture diagrams, etc.  This beast is too
> big for any single person to ride anymore, so please do help us :-).

Well I think, the big picture documentation can only be done by people
who at least have enough overview on the project and its history.
Since the project is growing more and more, this should be done very
soon...
* before the situation gets worse, and it will.
* because the larger the project becomes, the more important this kind
  of documentation will be for new developers and also for the project
  lead to plan the future of the project.

Regards,
 Florian

Re: Higher level project documentation, Was: Re: Other 2.6.2 changes

[Janne Jalkanen <Ja...@ecyrd.com>]

> Aren't there any tools which could analyze a code base and generate a
> project map / graphical class overview with dependencies a.s.o.?

Yes, there are, but these are in general useless, since they don't  
really describe how the software works.  Process diagrams and  
tutorials are far more useful.

> Well I think, the big picture documentation can only be done by people
> who at least have enough overview on the project and its history.

True, but we still need someone who is willing to take overall  
responsibility of the documentation and find the bits that need to be  
documented.  Also clean it up once someone writes some documentation,  
and makes sure it is organized well and is up to date.  I'm happy to  
contribute when someone says that "this bit here, that needs  
contribution from YOU since you understand it", but I can't take on  
the entire project management of the documentation, too...

/Janne