Re: Help with integrating Gnome docs into Ubuntu

[Matthew Paul Thomas <mpt myrealbox com>]

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.

Cheers
--
Matthew Paul Thomas
http://mpt.net.nz/