Geronimo Architecture Documentation

[Ryan Senior <rs...@mchsi.com>]

Hi all,

I'd like to write some in-depth architecture documentation for 
Geronimo.  I'm thinking it might be a little large for the wiki (maybe 
20 pages or more???).  Is there a preferred documentation format?  Maybe 
docbook?

Is there a particular part of the architecture that I should make sure 
to write about/focus on?  I was thinking that the interaction of the 
various GBeans would be a good place to start.

Thanks!

Ryan

Re: Geronimo Architecture Documentation

[Andrus Adamchik <an...@objectstyle.org>]

I don't see a problem with 20+ pages on Wiki. Geronimo and a number  
of other projects maintain their main doc sets via Confluence and it  
scales pretty well.

Andrus


On Sep 27, 2006, at 8:40 PM, Ryan Senior wrote:
> Hi all,
>
> I'd like to write some in-depth architecture documentation for  
> Geronimo.  I'm thinking it might be a little large for the wiki  
> (maybe 20 pages or more???).  Is there a preferred documentation  
> format?  Maybe docbook?
>
> Is there a particular part of the architecture that I should make  
> sure to write about/focus on?  I was thinking that the interaction  
> of the various GBeans would be a good place to start.
>
> Thanks!
>
> Ryan
>

Re: Geronimo Architecture Documentation

[Hernan Cunico <hc...@gmail.com>]

Hi Ryan,
That's great and I think the cwiki is the right place to host it. 20+ pages is not a lot for a section as long as we keep it well organized ;-)
If you want to I can give you some advise on how to structure things in Confluence.

Using other "format" than cwiki will divide the documentation again ( we just finished consolidating the documentation in one place and one format ). cwiki is powerful enough to allow users to export the entire space or just a part of it in several formats. For instance, if you are interested in just the architecture section from the entire documentation you can browse the space, select that particular "branch" and get it exported in a book-like PDF format for instance.

Cheers!
Hernan

Ryan Senior wrote:
> Hi all,
> 
> I'd like to write some in-depth architecture documentation for 
> Geronimo.  I'm thinking it might be a little large for the wiki (maybe 
> 20 pages or more???).  Is there a preferred documentation format?  Maybe 
> docbook?
> 
> Is there a particular part of the architecture that I should make sure 
> to write about/focus on?  I was thinking that the interaction of the 
> various GBeans would be a good place to start.
> 
> Thanks!
> 
> Ryan
> 

Re: Geronimo Architecture Documentation

[Jason Dillon <ja...@planet57.com>]

On Sep 29, 2006, at 7:22 AM, Matt Hogstrom wrote:
> I agree with the currency issue, however, at least they are a  
> starting point and in general I think most people want to read a  
> quick overview rather than check out an SVN tree (I said most, not  
> all).  Even if it became stale in a year it would be a huge  
> advantage for the project and new folks that want to check it out.

I think the docs will get stale much quicker than you think... but in  
general I agree that it would be better to have it.... just date the  
doc and state explicitly what tree/version it is based off of.

--jason

Re: Geronimo Architecture Documentation

[Matt Hogstrom <ma...@hogstrom.org>]

On Sep 28, 2006, at 5:07 AM, Jason Dillon wrote:

> Um... TeX or Docbook is probably much more "universal" in the open  
> source world than any bloated, expensive and buggy microsoft  
> unstableware.
>

Hehehe...I'm not sure which is more fun, sending an e-mail with a  
reference to Microsoft and waiting for the reply or reading your  
response :)


> And, while I think architecture docs are great... they tend to  
> become outdated very quickly, especially as we keep changing the  
> internals of the server.
>

I agree with the currency issue, however, at least they are a  
starting point and in general I think most people want to read a  
quick overview rather than check out an SVN tree (I said most, not  
all).  Even if it became stale in a year it would be a huge advantage  
for the project and new folks that want to check it out.

Lei capisce?

Matt Hogstrom
matt@hogstrom.org

Re: Geronimo Architecture Documentation

[Jason Dillon <ja...@planet57.com>]

Um... TeX or Docbook is probably much more "universal" in the open  
source world than any bloated, expensive and buggy microsoft  
unstableware.

And, while I think architecture docs are great... they tend to become  
outdated very quickly, especially as we keep changing the internals  
of the server.

--jason


On Sep 27, 2006, at 6:17 PM, Matt Hogstrom wrote:

> Well...Word format and Powerpoint as root formats is probably the  
> most universal (Matt ducks anticipating a wave of anti-microsoft  
> tomatoes) that are ultimately available as PDFs from the project.   
> OpenOffice sounds nice but in my experience its not very good and  
> less portable.
>
> On Sep 27, 2006, at 8:40 PM, Ryan Senior wrote:
>
>> Hi all,
>>
>> I'd like to write some in-depth architecture documentation for  
>> Geronimo.  I'm thinking it might be a little large for the wiki  
>> (maybe 20 pages or more???).  Is there a preferred documentation  
>> format?  Maybe docbook?
>>
>> Is there a particular part of the architecture that I should make  
>> sure to write about/focus on?  I was thinking that the interaction  
>> of the various GBeans would be a good place to start.
>>
>> Thanks!
>>
>> Ryan
>>
>>
>
> Matt Hogstrom
> matt@hogstrom.org
>
>
>

Re: Geronimo Architecture Documentation

[Matt Hogstrom <ma...@hogstrom.org>]

Well...Word format and Powerpoint as root formats is probably the  
most universal (Matt ducks anticipating a wave of anti-microsoft  
tomatoes) that are ultimately available as PDFs from the project.   
OpenOffice sounds nice but in my experience its not very good and  
less portable.

On Sep 27, 2006, at 8:40 PM, Ryan Senior wrote:

> Hi all,
>
> I'd like to write some in-depth architecture documentation for  
> Geronimo.  I'm thinking it might be a little large for the wiki  
> (maybe 20 pages or more???).  Is there a preferred documentation  
> format?  Maybe docbook?
>
> Is there a particular part of the architecture that I should make  
> sure to write about/focus on?  I was thinking that the interaction  
> of the various GBeans would be a good place to start.
>
> Thanks!
>
> Ryan
>
>

Matt Hogstrom
matt@hogstrom.org