Re: Questions (was: Re: A Critique: Getting Started with GNUstep on Windows)

[Richard Frith-Macdonald]

> On 26 Feb 2016, at 11:49, Gregory Casamento <greg.casamento@gmail.com> wrote:
> 
> Richard,
> 
> I only have a response for one thing regarding autogsdoc...
> 
> On Friday, February 26, 2016, Richard Frith-Macdonald 
> <richard.frith-macdonald@brainstorm.co.uk> wrote:
> 
> > On 26 Feb 2016, at 05:35, Svetlana A. Tkachenko <svetlana@members.fsf.org> 
> > wrote:
> >
> > Gregory Casamento wrote:
> >> Speaking of documentation I am of the
> >> concerted opinion that we should do away with autogsdoc.  The reason
> >> for this is because it is yet another example of NIH.
> >
> > ... not invented here?
> 
> Not true ... it just pre-dates popular auto-documentation, and long pre-dates 
> anything that understood ObjC, so was started before other options were 
> available.
> GNUstep is an old project, and there's quite a bit of stuff like that which, 
> to the uninformed looks like NIH, but in fact is just the way it is because 
> it pre-dates alternative free software implementations.
> 
> Yes.  I am very much well aware of this fact.   Many things in GNUstep 
> predate other projects.  I've been with the project almost 20 years. :)  
> 
> My point in saying NIH is that, at some point, and for some things (like 
> autogsdoc), it is better to let them go instead of holding on for legacy 
> reasons.  It might be nice to have some really gorgeous documentation for 
> GNUstep generated by a tool created by a project whose dedicated purpose is 
> to make really nice documentation. 
> 
> Just a thought. At this point autogsdoc creates HTML and looks like 
> documentation from the early 90s.   This could be improved with CSS, but I 
> wonder if moving to something like "appledoc" (a project meant to duplicate 
> apples documentation look and feel) or doxygen might not be a good idea. 

Nobody is 'holding on' to anything.
Leaving aside the issue of what's least effort (ie is it more efficient to 
re-style existing doc output ... a 'relatively' small job), nobody is 
volunteering to go through and edit all the source code and do the work to 
replace what we have with a new, improved automated documentation system, or 
even to implement a new system as a demonstration to encourage people to edit 
exisitng source gradually.

Saying we'll adopt a new set of software is a vain hope of a techno-fix for a 
non-technological problem.

It's not that we lack effective documentation because we aren't using some 
particular brand of software, we lack it because nobody wants to produce it.

There's no barrier to volunteers in having the system we have; because there's 
no compulsion for any volunteer to use it.
It's not as though, if someone creates some really nice looking documentation, 
anyone is going to say 'gosh no, take it away'.
On the contrary, if a good enough system were added (eg something similarly 
integrated and easy to use, but prettier), people might be motivated to help 
converting existing code/documentation.

But in a volunteer-based system,  people must *demonstrate* improvement to 
encourage others;  you don't just say that the existing stuff is not good 
enough, since doing that just makes the existing volunteers unhappy.

That's actually why I consider the thread from which this email originated to 
be a troll.

When someone simply complains about a free software project this way, at best 
they are just venting their frustration, however much they try to dress it up 
as 'constructive' criticism, what they are doing only serves to discourage both 
existing and any prospective volunteers who happen to read the thread.

Let's not be sucked into that.

We have a load of good stuff.  We already know there's huge room for 
improvement.  We are *very* open to anyone who wants to come help improve 
things, in *all* areas.
But we should facilitate people actually coming and helping, not just say that 
we'll change something when someone complains.

Who is the 'we' that will make those changes?  While I've always been the main 
advocate for API documentation, even I know that it is absolutely NO block to 
developers (who can easily check Apple's docs and the headers/source).
I can certainly argue the case for improved documentation and would love 
someone to improve things, but it's not a job for core developers/maintainers.

So the 'we' who would do all the work for this has to be someone who, afaik, 
does not exist (hasn't volunteered).

I'll always try to find time to help people who want to come and help the 
project (advice based on familiarity with the code, smallish coding changes and 
specific target-oriented bugfixes etc), but when it comes to documentation, if 
I had time to spare, I'd spend it on *content* (eg documenting GNUstep specific 
stuff like renaissance) rather than on presentation of what's largely 
duplication/restatement of Cocoa API documentation.