Re: First ideas

[Federico Mena Quintero <federico ximian com>]

On Fri, 2005-11-18 at 08:22 -0500, Luis Villa wrote:
> More carrot, less stick?

Why, that's exactly what I'm trying to figure out :)

Let's ignore the fixed/total bugs ratio for now; that's a neurotic
stats-taking thing of mine.  I'm sure it would produce interesting
numbers.

About requiring documentation for libraries:

The core GNOME hackers are not the audience for these docs.  They are
good enough programmers that they can grok our libraries simply by
looking at header files, or looking for examples of usage in the core
GNOME programs themselves.

The audicence for these docs is the average programmer, out there in the
wild.

If we want to achieve 10x10, we'll need GNOME to have apps that end
users will want to use.  The only way to get these apps written is to
make it possible for random developers to understand the GNOME platform.

I'm afraid that there's not much of a carrot right now *for us*.  There
is a carrot if you care about 10x10.  The only carrot would be to win in
a competition upon gtk-doc's stats of "n% coverage" - that's meaningful
for reference docs, not for tutorials, of course :)

Also, I'll contend that the best person to write docs for an API is the
person who wrote that API.

And once you get into the habit of documenting your APIs, you see that
yes, it takes a little effort, but it's not a big deal, either.

During the early days of GNOME 2.x, we had a *hard* time getting used to
the idea that the ABI/API couldn't change, just get additions.  In GNOME
1.x we were used to changing APIs all the time if they didn't do what we
wanted.  

The early days of 2.x consisted of learning how to design better APIs in
the first place, so that we wouldn't need to change them later.  Why do
you think we have so many deprecable libraries right now?  Part of it is
that their APIs suck, and part is that they also happen to be pretty
under/un-documented.  They are the "there's only one person that
understands this" kind of libraries.

So, yes, I think at first we would have a mildly hard time getting used
to the idea that we need to document our libraries.  In a year or two
everyone would be used to it and they would just do it naturally.  Once
we achieve that, you may see me pestering the release team to no-go on
libraries which don't have unit tests ;)

But one thing at a time, Pinky.

  Federico