Documentation woes

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

I think there is a major and unacceptable problem with the indexing  
of the current 2.1 docs.  Some time ago I implemented a little  
feature for app-specific log4j configuration and actually wrote up  
some instructions on how to use it.  Today I wanted to see what I had  
written and discovered that while it's possible to find using google  
search it isn't really possible to find from the top level  
documentation page.

It ain't here:

http://cwiki.apache.org/GMOxDOC21/documentation.html

There are a whole lotta unwritten topics listed under Development and  
deployment planning, but not mine!

If you click the link... you do get http://cwiki.apache.org/GMOxDOC21/ 
development-and-deployment-planning.html which has my little  
contribution.

Perhaps I'm overreacting but this seems like an enormous problem to  
me.  I'd far prefer that all the index pages be generated  
automatically from the page hierarchy even if this means the entries  
show up an a more random (alphabetical?) order as long as the indices  
are complete and up to date.  I don't really get much from little  
green check marks when content that someone has actually gone to the  
trouble to write is not reflected and easily accessible.

thanks
david jencks

Re: Documentation woes

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

Fixed, I added a macro to automatically list all children pages of "Development and deployment planning".
These pages are now visible from http://cwiki.apache.org/GMOxDOC21/documentation.html

Sorry it took this long to update this. The original TOC on the front page was put there as a guideline for developing some of the content; as we fill the doc with more content we need to update the corresponding sections. I still believe it looks a lot better if we force some structure on the front page compared to a having a massive list alphabetically ordered. Just compare 20 doc vs 21.

Thanks for contributing to the doc !

Cheers!
Hernan

David Jencks wrote:
> I think there is a major and unacceptable problem with the indexing of 
> the current 2.1 docs.  Some time ago I implemented a little feature for 
> app-specific log4j configuration and actually wrote up some instructions 
> on how to use it.  Today I wanted to see what I had written and 
> discovered that while it's possible to find using google search it isn't 
> really possible to find from the top level documentation page.
> 
> It ain't here:
> 
> http://cwiki.apache.org/GMOxDOC21/documentation.html
> 
> There are a whole lotta unwritten topics listed under Development and 
> deployment planning, but not mine!
> 
> If you click the link... you do get 
> http://cwiki.apache.org/GMOxDOC21/development-and-deployment-planning.html 
> which has my little contribution.
> 
> Perhaps I'm overreacting but this seems like an enormous problem to me.  
> I'd far prefer that all the index pages be generated automatically from 
> the page hierarchy even if this means the entries show up an a more 
> random (alphabetical?) order as long as the indices are complete and up 
> to date.  I don't really get much from little green check marks when 
> content that someone has actually gone to the trouble to write is not 
> reflected and easily accessible.
> 
> thanks
> david jencks
> 
>