Re: On Documentation

[Mark McLoughlin <markmc redhat com>]

Hi Federico,

On Fri, 2004-07-23 at 02:21, Federico Mena Quintero wrote:
> On Wed, 2004-07-21 at 02:36 -0500, Shaun McCance wrote:
> 
> > 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.
> 
> Maybe it is time to bite the bullet and decide that new modules can't go
> in unless they come with their respective manuals.  And if they are
> libraries, they should come with at least complete gtk-doc coverage.  We
> can't be serious about presenting GNOME to people as a serious
> development platform unless it has good documentation.

	(Ignoring the issue of API documentation - that is perhaps something
worth considering, but its help documentation which Shaun is talking
about.)

	Shaun and I discussed this a bit on irc before Shaun sent the mail. I
was curious whether Shaun's emails were intended to imply that
undocumented modules should be looked at unfavourably during this
process.

	My take on this is that the real problem here is that GNOME doesn't
have a healthy documentation community right now. The real problem is
not that proposed modules don't have documentation, or that hackers are
lame for not writing documentation, or that some modules are hard to
document than others[1], or that there might resistance to adding help
documentation to these modules.

	The reality is that we *expect* documentation to come from the GDP
(i.e. if a module appears with documentation which didn't come from the
GDP, you'd be surprised), so without a healthy GDP community we cannot
expect documentation for all proposed modules.

	This is similar to i18n, and to a lesser extent a11y. We don't expect
hackers to come along with new modules translated into 40 different
languages, nor do we expect them to come along with fully accessible
software. In the case of i18n, we have a sub-project which takes
responsibility for that work and, for a11y, a sub-project which supports
hackers in making their software fully accessible. We don't expect this
stuff done upfront, but we do expect that new module maintainers be
amenable to working with the sub-projects to get this stuff done in a
timely manner.

	I do believe that a fully documented GNOME is a very important and
worthy goal. But the solution to that is to work on growing the GDP
community, not block the addition of new feature to GNOME on the lack of
a healthy documentation community.

Cheers,
Mark.

[1] - Well, that might be an issue - but only in the sense of poor
usability, badly designed interaction, whatever.