Re: Help with integrating Gnome docs into Ubuntu

[Shaun McCance <shaunm gnome org>]

On Sun, 2007-07-15 at 03:31 +1200, Matthew Paul Thomas wrote:
> On Jul 5, 2007, at 7:30 PM, Matthew East wrote:
> > ...
> > The basic problem we are having though is that Ubuntu customises quite 
> > a lot of Gnome, and as a result the Gnome documentation is wrong, and 
> > we need to correct it. An example is the layout of the System menu, 
> > which in Ubuntu does not contain the screenshot/lockscreen buttons, 
> > but which are part of vanilla Gnome and therefore documented in the 
> > Gnome user guide.
> >
> > The two possible ways of correcting these are:
> >
> > 1. Creating patches on the Gnome documentation in the Ubuntu packages 
> > of gnome-user-docs.
> > 2. Creating a separate tree with a copy of the Gnome documentation (to
> > be updated from time to time) and shipping it separately in a new
> > package, or with the Ubuntu-specific documentation.
> > ...
> 
> There is a third way: Use distributed version control.
> 
> The GDP could have its own branch, Ubuntu could have its own branch, 
> and any other distributor that used a customized Gnome could have its 
> own branch. Ubuntu could merge any useful changes from the GDP, while 
> ignoring those that weren't relevant to Ubuntu. The GDP could merge any 
> useful changes from Ubuntu, while ignoring those that apply to 
> Ubuntu-specific customizations. And if two or more distributors made 
> the same customizations, they could merge corresponding documentation 
> changes from each other.
> 
> Not only do I think this would work well, I think in the long term it's 
> the only approach that *can* work well. As long as any distributor 
> makes long-lived customizations to Gnome, they will need to maintain 
> their own variation of the help. (Ubuntu 7.04's help is a marvellous 
> papering over of the cracks, but drill down and there's plenty of 
> falsity caused by Ubuntu's Gnome customizations.) As long as any 
> operating system contains software not included in stock Gnome, the 
> help will need to take that into account. And as long as the GDP is 
> short of contributors (has it ever not been?), it will benefit from 
> sharing effort with the help and documentation teams of distributors.
> 
> This is partly why, last September, I said "it would be really really 
> cool if the Gnome help assumed that people using Gnome are using an 
> operating system based on Gnome". 
> <http://urlx.org/mail.gnome.org/01f05> It is also partly why, in the 
> same message, I said the GFDL was a bad license to use for 
> documentation: while it is dodgy even with centralized version control, 
> it would be positively awful with distributed version control.

Sorry I didn't reply to this sooner.

First, a Mallard plug:  When Mallard gets off the ground,
many of these issues will become simpler.  For instance,
if Ubuntu adds "core" applications that you think should
be discussed in the User Guide, you can just create your
own pages for those applications.  Plop those pages down
alongside the rest of the UG, and presto!  They're part
of the User Guide.

That said, there will still be issues with things like
changing the layout of the System menu.  Adding content
(think plugins) is made simple by Mallard.  But changing
content (think patches) is still thorny.  I suspect that
patches will be slightly easier to maintain because the
source material is already paginated, but you're still
maintaining patches.

Could distributed version control help alleviate these
issues?  Possibly.  I'm not a big version control geek,
so I haven't really played with these other systems.
But it's unlikely the GDP upstream is going to change
systems unless Gnome does so.  Although I think I've
seen people blog about using bzr and git with bridges
to svn, so maybe you guys can do that on your end.

This is why I generally don't like vendor customizations.
The cost of maintaining a code patch is generally very
low compared to the cost of the auxiliary patches, such
as documentation and translation.

--
Shaun