Re: GNUStep Documentation– General Improvements

[Riccardo Mottola]

Hi,
> 1. The first of which is that in order to find the pages containing the
> information generated by autogsdoc one has to scoure the site, even though
> reference documentation should be easy to find.  A link to the reference
> documentation shouuld appear on the main page instead of a link on a page
> form the sidebar at the bottom on the wiki page.
>    
the reference documentation is directly available form the site without 
going to the wiki. To be certain, it is available there too.
On the main page, select "developers", which sounds pretty reasonable, 
on the side bar. on that page "Manual and documentation" should be 
pretty evident.

Using a search engine ( tried bing) for "gnustep base reference" yields 
the index as first result.

I personally find it very useful to install the documentation on my 
local HDD. Just "make install" inside documentation of base, gui, back.
> 2. GNUStep uses it's own proprietary documentation genrator when perfectly
> good Objective-C document generators such as Doxygene are available, and
> also produce less bland more readably, clean and easily navigatable
> documentation.  These doccument generators also have multiple output
> formats.
>    
I think your own generator is quite good, it has no additional 
dependencies than gnustep itsels and writing comments for it is not that 
difficult.

> 3.  Required delegate methods should be indicated by differently colored
> headers and anchor links.
>    
could be a good idea.
> 4.  The example program page does not contain the sample code from the
> sample programs, only their .app packages, this is generally a good demo,
> but not helpful from a prgramming prespective.
>
>    
What do you refer to? the gnustep examples contain full source code.

> If you agree and think things should change or you think I am in error feel
> free to post your thoughts.  Making documentation easily readible, and
> providing useful samples should be a priority in order to attract
> developpers to the GNUStep platform.
>    
Agreed. In fact what is most disturbing for is that it is incomplete.

Riccardo