Re: GNUStep Documentation– General Improvements

[Gregory Casamento]

Just a few thoughts...  my comments follow in-line....

On Sat, Sep 3, 2011 at 8:31 PM, BTS <awiebe@burningthumb.com> wrote:
>
> There are a number of things that concern me about the manner in which
> GNUStep is doccumented.
>
> 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.

Absolutely true.   The documentation should be more readily available.

> 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.

The reason for this is because GNUstep had this document generator
before Doxygene existed.   In fact there was some debate when Doxygene
first came out whether we should switch to it.   I believe we should
re-examine this possibility now if possible.   autogsdoc is a useful
tool, but it would also be nice to see if Doxygene could be used, if
it's not too much work to make this happen.

> 3.  Required delegate methods should be indicated by differently colored
> headers and anchor links.

I agree.   This would be helpful.

> 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.

This also would be helpful.

> 5.  The GNUStep documentation does not reference sample code– even
> referencing apple sample code would be useful, though optimally apple sample
> code should be tested using GS APIs

Yes, indeed.

> 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.

GC

-- 
Gregory Casamento - GNUstep Lead/Principal Consultant, OLC, Inc.
yahoo/skype: greg_casamento, aol: gjcasa
(240)274-9630 (Cell)