Re: GNUStep Documentation– General Improvements

[Richard Frith-Macdonald]

On 4 Sep 2011, at 01:31, BTS 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.

I agree that better links would be good from the website/wiki ... but bear in 
mind that you are talking about developer api documentation here ... the reader 
is normally expected to have this documentation locally on their own machine.

> 2. GNUStep uses it's own proprietary documentation genrator

Actually, it's a non-proprietory, open format and *free* tool usable by anyone, 
but it was designed for ObjC/GNustep.

> when perfectly
> good Objective-C document generators such as Doxygene are available,

But they weren't when the original markup language was designed (1997).  I 
think the gnustep documentation markup language pre-dates Doxygen, and while I 
agree that Doxygen's presentation is now much better, the autogsdoc stuff still 
has advantages (not least of which is the fact that you can install gnustep and 
generate the documentation without needing an external package).

> and
> also produce less bland more readably, clean and easily navigatable
> documentation.  These doccument generators also have multiple output
> formats.

autogsdoc is designed that way too (a big part of the reason the original 
markup language was done as xml was to facilitate the use of technologies like 
xslt to produce different output formats) ... but nobody's bothered to 
implement concrete formats.
It would be good to improve this (or adopt some format like Doxygen, if someone 
would volunteer to change all the source/headers/makefiles and add any missing 
features to Doxygen).

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

I'm not sure about that (generally I dislike a proliferation of different link 
colors), but it might be worth doing something to identify delegate methods.

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

Yes, we are constantly looking for someone to volunteer to improve 
documentation.