On Documentation

[Shaun McCance <shaunm gnome org>]

(This is my analysis of my analyses of the documentation, wearing my
GDP FL hat.  This is not my opinion of me or my appropriateness for
inclusion in the Gnome desktop.)

There was some confusion (on IRC) about the intent of my emails about
the documentation for each of the proposed modules, so I want to clear
that up.  I do not have veto power on any proposals, nor do I want it.
I'm not saying that these modules should or should not be included, and
I'm certainly not trying to block our releases.

Ideally, we'd like every release to go out fully documented.  But we're
a free software project firmly committed to time-based releases, so that
isn't always possible.  I'm sure the translation and accessibility teams
would love 100% completion as well.  And we'd all love to ship a release
with no bugs.

The decision on whether or not a particular module is included is made
by the community.  I think most of us take quality into account when
making our own decisions, and I consider documentation quality to be
part of the overall quality of the application.  I'm trying to keep
people informed on the quality of the documentation and give some idea
of how much we can expect to improve it in the next two months.  That
way people can take that into account when making their decisions, if
they choose to.

The documentation team is very under-staffed this cycle.  We do have
some eager new contributors, but it takes time to get people ramped up
completely.  Please understand that proposing an undocumented module for
inclusion in 2.8 may very well be equivalent to proposing that I write
complete documentation for that module from scratch in one month.  As I
mentioned a few days ago, I'm effectively taking a break from coding for
the rest of this release cycle to do documentation work.

We are doing the best we can with what we have right now.  I just want
people to understand that documentation doesn't magically appear, and
that new modules could very well ship with insufficient documentation.

--
Shaun