Re: Feed Back on Documentation

[Shaun McCance <shaunm gnome org>]

On Fri, 2008-04-11 at 16:04 +0100, Matthew East wrote:
> hi,
> 
> On Thu, Apr 10, 2008 at 11:51 PM, Leonardo Fontenelle
> <leo fontenelle gmail com> wrote:
> > I'm aware that many of the recent translation updates in upstream GNOME
> > were contributed by Ubuntu, but maybe (more) Ubuntu documentation
> > writers should work directly upstream. The result would be easier
> > maintenance downstream, and further enhancement of upstream
> > documentation. (At least, that's the experience of Ubuntu's pt_BR l10n
> > team.)
> 
> Whenever we touch something that is "Gnome" related, we contribute it
> upstream. The team has worked upstream on Brasero documentation and
> contributed the occasional patch to the user-guide and
> accessibility-guide.

This is true.  Of all the distros, Ubuntu has been the
best about contributing documentation work upstream.

>  However, the current setup of Gnome documentation
> is that really the majority of Ubuntu documentation is unsuitable for
> contribution upstream.
> 
> That may be made easier in Mallard though.

I think it will, although it won't be magically trivial.
Mallard makes it easy to plug new pages in without really
modifying the original document.  So if Ubuntu adds some
preferences tool, the Ubuntu documentation people can
just write a page or two about it.  No patches.

But if they need to modify the contents of an existing
page, that will still require a patch.  Since topics are
organized into pages, which are each in separate files,
I think patch management will be considerably simpler.

There are basically two reasons downstream would want
to patch an existing page: either it's out of date, or
they've made a software change downstream that needs to
be reflected in the documentation.  If it's the former,
they can easily send us a patch for the page.  If it's
the latter, we're not really interested in the patch.

But when we get into trouble is when both are true.
Obviously, it's possible to first patch it to bring
it up to date, then patch against the patched version
for downstream-specific changes.  But that's more
work, and I don't think anybody will do it.

But I think this will help us work better upstream.
A paginated format means we can more easily assign
small chunks of tasks.  If somebody comes in looking
for something to do[1], we can point to a page that's
out of date.  It's an afternoon job.  Bite-sized jobs
will help us get new contributors.

[1] This happens a lot, and we mostly fail to keep
them around, mostly because we never know what to
ask them to do.

--
Shaun