[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Gregory Casamento
Subject: Re: Questions (was: Re: A Critique: Getting Started with GNUstep on Windows)
Date: Fri, 26 Feb 2016 17:06:09 -0500


On Fri, Feb 26, 2016 at 8:39 AM, Richard Frith-Macdonald <address@hidden> wrote:

> On 26 Feb 2016, at 11:49, Gregory Casamento <address@hidden> wrote:
> Richard,
> I only have a response for one thing regarding autogsdoc...
> On Friday, February 26, 2016, Richard Frith-Macdonald <address@hidden> wrote:
> > On 26 Feb 2016, at 05:35, Svetlana A. Tkachenko <address@hidden> 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.

​I should be clear that when I suggest a change I am more than willing to take it on.   I have no problem in doing so as you have seen in the past with many things.  What I'm doing is asking if this is something that might be welcomed before I go and put time into such changes.  

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.

​I'm not sure why you see Thom's video as complaining.   He has stated to me that he is willing to help solve some of these issues with us.   What Thom was trying to illustrate is that the initial experience for one sector of our developers is currently very substandard.​

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.

​We have tons of good stuff and, as such, we should make it easier to access and get to and contribute to.​

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.

​Speaking for myself.  With any change *I* propose.  I am ready and willing to make said changes.  In my view in this project there is no "we."  I work on GNUstep for fun and I don't pretend to try to tell people what GNUstep should be to them.  I only know what GNUstep is FOR ME.​

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

​Me is We in all cases where I say I want or need something.  I put it out there in the hope that other "me's" will feel the same and we can come together as a "we." ;)​

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.


Gregory Casamento
GNUstep Lead Developer / OLC, Principal Consultant
http://www.gnustep.org - http://heronsperch.blogspot.com

reply via email to

[Prev in Thread] Current Thread [Next in Thread]