Top level documentation organization nitpicks

[David Jencks <da...@yahoo.com>]

I keep having some minor annoyances starting from http:// 
geronimo.apache.org/documentation.html and hope someone who knows  
where that page comes from and more about how some of the rest of the  
site is set up can fix them.

1. I'd really like a direct link from the documentation front page to  
the project management wiki.  I can't remember how to get to the  
release process docs from the front page.
2. The views of what is in the project management wiki seem to be  
inconsistent.

http://cwiki.apache.org/geronimo/ has a page where the pm wiki  
contents have the release process doc listed last.
http://cwiki.apache.org/GMOxPMGT/documentation.html does too
http://cwiki.apache.org/GMOxPMGT/apache-geronimo-development- 
process.html has a really different organization.

I don't know if its possible but it sort of looks to me as if some of  
these pages are generated more automatically than others and perhaps  
relying always on the automatically generated views could reduce the  
amount of inconsistency.

thanks
david jencks

Re: Top level documentation organization nitpicks

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

I just added a link on the staging web site (http://cwiki.apache.org/GMOxSITE).
Look into the "Overview" menu box, if no one opposes I'll just leave it there and it will get propagated to the live site in about 1 hour or so.

Cheers!
Hernan

Hernan Cunico wrote:
> 
> David Jencks wrote:
>> I keep having some minor annoyances starting from 
>> http://geronimo.apache.org/documentation.html and hope someone who 
>> knows where that page comes from and more about how some of the rest 
>> of the site is set up can fix them.
> 
> http://geronimo.apache.org/documentation.html is basically updated 
> manually. Given the Geronimo main web site resides on a different server 
> from where we serve the wiki, and a limitation in the auto export 
> plugin, we cannot generate this page automatically.
> 
> http://geronimo.apache.org/documentation.html (main site) and 
> http://cwiki.apache.org/geronimo (wiki home page) are not meant to be 
> the same. Most of the updates on 
> http://geronimo.apache.org/documentation.html occur around new releases 
> time frame and it's done by committers. The wiki on the other hand is 
> updated daily and by any contributor.
> 
> The documentation home page http://cwiki.apache.org/geronimo (wiki) 
> builds up mostly automatically from the content on the other confluence 
> spaces such as GMOxPMGT for the Project Management.
> This is the markup that does that:
> 
> h3. Project management
> 
> *[*Apache Geronimo Project Management*|GMOxPMGT:Documentation]*
> {children:page=GMOxPMGT:Documentation|all=true}
> 
> But again, this won't work from the main web site 
> (http://geronimo.apache.org)
> 
>>
>> 1. I'd really like a direct link from the documentation front page to 
>> the project management wiki.  I can't remember how to get to the 
>> release process docs from the front page.
> 
> If you start your search from the documentation home page 
> http://cwiki.apache.org/geronimo (wiki) there already is a direct link 
> there to all the topics in the Apache Geronimo Project Management space 
> (GMOxPMGT)
> 
> Having said this, we can still add a link to the Geronimo release 
> process page from the web site directly to the wiki. I think the best 
> place to add this link would be in the "Overview" menu box.
> 
>> 2. The views of what is in the project management wiki seem to be 
>> inconsistent. 
>> http://cwiki.apache.org/geronimo/ has a page where the pm wiki 
>> contents have the release process doc listed last.
> 
> the macro we use for generating this lists automatically only allow 
> alphabetical order (asc or desc). The only way to address this issue is 
> to manually build the table of contents but we may have problems trying 
> to keep them up to date.
>> http://cwiki.apache.org/GMOxPMGT/documentation.html does too
> 
> http://cwiki.apache.org/geronimo/ is based on the content listed on 
> http://cwiki.apache.org/GMOxPMGT/documentation.html so these two should 
> be the same.
> 
> 
>> http://cwiki.apache.org/GMOxPMGT/apache-geronimo-development-process.html 
>> has a really different organization.
> 
> The TOC on this page is not generated automatically. Actually I haven't 
> looked at this page in quite some time so maybe I should update it to 
> generate the TOC automatically just like to other sections.  Either way 
> I think there is a lot of info on this space that could use some 
> "housekeeping".
> 
>>
>> I don't know if its possible but it sort of looks to me as if some of 
>> these pages are generated more automatically than others and perhaps 
>> relying always on the automatically generated views could reduce the 
>> amount of inconsistency.
> 
> One last thing on the autoexport plugin, not necessarily an issue but it 
> still a PITA. The autoexport plugin can not realize that the 
> automatically generated TOC on space "A" has changed so it updates 
> another depending TOC on space "B". So I manually run auto exports on 
> the Geronimo spaces to make sure these changes (e g in the TOC) get 
> reflected all across GMOx sapes.
> 
> Last time I checked there was no way to schedule a job to do this 
> automatically.
> 
> HTH to clarify a little bit how this "monster" work. ;-)
> 
> Cheers!
> Hernan
> 
>>
>> thanks
>> david jencks
>>
> 

Re: Top level documentation organization nitpicks

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

David Jencks wrote:
> I keep having some minor annoyances starting 
> from http://geronimo.apache.org/documentation.html and hope someone who 
> knows where that page comes from and more about how some of the rest of 
> the site is set up can fix them.

http://geronimo.apache.org/documentation.html is basically updated manually. Given the Geronimo main web site resides on a different server from where we serve the wiki, and a limitation in the auto export plugin, we cannot generate this page automatically.

http://geronimo.apache.org/documentation.html (main site) and http://cwiki.apache.org/geronimo (wiki home page) are not meant to be the same. Most of the updates on http://geronimo.apache.org/documentation.html occur around new releases time frame and it's done by committers. The wiki on the other hand is updated daily and by any contributor.

The documentation home page http://cwiki.apache.org/geronimo (wiki) builds up mostly automatically from the content on the other confluence spaces such as GMOxPMGT for the Project Management.
This is the markup that does that:

h3. Project management

*[*Apache Geronimo Project Management*|GMOxPMGT:Documentation]*
{children:page=GMOxPMGT:Documentation|all=true}

But again, this won't work from the main web site (http://geronimo.apache.org)

> 
> 1. I'd really like a direct link from the documentation front page to 
> the project management wiki.  I can't remember how to get to the release 
> process docs from the front page.

If you start your search from the documentation home page http://cwiki.apache.org/geronimo (wiki) there already is a direct link there to all the topics in the Apache Geronimo Project Management space (GMOxPMGT)

Having said this, we can still add a link to the Geronimo release process page from the web site directly to the wiki. I think the best place to add this link would be in the "Overview" menu box.

> 2. The views of what is in the project management wiki seem to be 
> inconsistent.  
> 
> http://cwiki.apache.org/geronimo/ has a page where the pm wiki contents 
> have the release process doc listed last.

the macro we use for generating this lists automatically only allow alphabetical order (asc or desc). The only way to address this issue is to manually build the table of contents but we may have problems trying to keep them up to date. 

> http://cwiki.apache.org/GMOxPMGT/documentation.html does too

http://cwiki.apache.org/geronimo/ is based on the content listed on http://cwiki.apache.org/GMOxPMGT/documentation.html so these two should be the same.


> http://cwiki.apache.org/GMOxPMGT/apache-geronimo-development-process.html 
> has a really different organization.

The TOC on this page is not generated automatically. Actually I haven't looked at this page in quite some time so maybe I should update it to generate the TOC automatically just like to other sections.  Either way I think there is a lot of info on this space that could use some "housekeeping".

> 
> I don't know if its possible but it sort of looks to me as if some of 
> these pages are generated more automatically than others and perhaps 
> relying always on the automatically generated views could reduce the 
> amount of inconsistency.

One last thing on the autoexport plugin, not necessarily an issue but it still a PITA. The autoexport plugin can not realize that the automatically generated TOC on space "A" has changed so it updates another depending TOC on space "B". So I manually run auto exports on the Geronimo spaces to make sure these changes (e g in the TOC) get reflected all across GMOx sapes.

Last time I checked there was no way to schedule a job to do this automatically.

HTH to clarify a little bit how this "monster" work. ;-)

Cheers!
Hernan

> 
> thanks
> david jencks
>