|
| 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 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.
| [Prev in Thread] | Current Thread | [Next in Thread] |