Documentation development infrastructure

[Matt Zimmerman]

On Mon, Jan 24, 2005 at 10:37:45AM +0200, Sean Wheller wrote:

> If it was a nice to have I would not be pushing so hard. To clear why.

We currently manage all of the software in Ubuntu without a revision control
system at all, so you'll understand why it's difficult to believe that
documentation can't be developed without a specific, recent version of
Subversion.

We're going to move toward Bazaar in a big way in the future, but we've
acknowledged that neither we nor Bazaar are quite ready for that yet.

> Now GNOME docs are not in SVN, but in CVS. Furthermore, the docs are stored 
> with each app, usually under the directory appname/C/help/ . This means a 
> vendor drop is not just one checkout, but many. Unless you want to bring the 
> app src code into your repository too. In this case we don't need that so we 
> just want the appname/C/help/ from each app in GNOME CVS. I have automated 
> this and updates using scripts.
> 
> As far as I can see this process may be easier under Bazaar, but the basic 
> principle is the same. I will look into this is people decide to move to 
> Bazaar (Please advise). Only by having a copy of the GNOME doc in the writers 
> Working Copy can XInclude/XPointer work for building.
>
> Now in certain cases writers will need to make changes in the GNOME part of 
> the section outlined above. In thi scase we must decide if this is GNOME 
> specific or ubuntu specific. If the change is GNOME specific we should try to 
> patch and move it upstream.
> 
> So the Ubuntu docs can be viewed as a patch on the GNOME docs. To manage this 
> effectively, the concept of vendor drops is the most efficient.

If I understand your approach, I think that Bazaar would be the natural
choice for this implementation.  However, it does sound somewhat
overcomplicated to me, given the scope of the work.

Is there no reasonable way to meet your goals which doesn't involve a
complex and difficult revision control infrastructure?

> In short we need this because it will enable the doc team to produce
> Ubuntu docs in the most efficient manner. There is no point rewriting what
> GNOME or any other desktop have done. The time required with current human
> resources will be more than a year. People may not know this, but a single
> page of documentation, done properly, takes on average 5 hours to reach
> final production quality. So if you have a 100 page book it probably took
> 500 hours. We can drastically reduce this by building on top of GNOME or
> any other Desktops work.

We would all like to have the ideal development environment, but in
practice, we generally settle for something which works, and imposes a
minimal maintenance burden (both on the development team and the system
administrators), and move ahead when the next generation of infrastructure
is sufficiently mature.

Trying to shoot for the ideal in the very beginning inevitably causes a lot
of difficulty, and it is easy to get caught spending more time trying to get
the infrastructure right than actually working on the product.  This
tradeoff comes up time and time again in IT, and is especially applicable
when working with leading-edge software features.

I think it's a great idea to build on top of work done in other projects,
such as GNOME, but in the absence of an ideal RCS to manage it all, I think
it is still possible to make use of that work.

It's entirely possible that Robert will step in and say that Bazaar is
perfect for your needs, and that someone can assist you in getting it set
up, but my guess is that it would be in our best interest to keep things
simple for now.

-- 
 - mdz