Documentation development infrastructure

Tue Jan 25 05:53:44 UTC 2005

On Tuesday 25 January 2005 03:01, Matt Zimmerman wrote:
> 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.

I am shocked. Would be intersting to see how you guys manage things.

>
> 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.

Agreed. Bazaar looks great. Although reading about it I can see that there are 
still many things to do. But the basics are there for a production system. 
What's stopping devel from doing this? Am I missing something? I mean my 
local tests of Bazaar is that it is not much different than tla and so far I 
have not managed to mess it up.

>
> > 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?

Yes. Bazaar using the arch mirrors would be ideal. However, remember that at 
time of writing, this was not an option. In face of a situation where people 
here are just talking about Bazaar and there is a planned sandbox for people 
to learn, it did not seem like a solution. So I was looking for solutions in 
SVN.

Belive me I tried a few ideas to get the solution to work and finally decided 
that using symlinks would be easiest. Unfortunately that is only supported 
SVN 1.1.1 or higher. In short I tried to find a easy method of managing what 
can be a complex thing, using the current platform. I was not aware, no did I 
think that using a newer version would be such a pain.

As for the method of XInclude/XPointer it is a common practice in Docbook and 
very much akin to the Object Oriented methods used in other programming 
languages. OO just makes sense, sure you will agree.

Again the reason for moving in this direction was driven by:
1. Few people actually writing and committing.
2. A realization that there is much work upstream to be reused.
3. A need to do things efficiently in light of a very small team.

Like everyone I don't have much time, but what time I do have is planned and 
focused on reaching Hoary. I can choose to do things the hard and long way 
and so waste time, or I can spend time at the beginning making things quick 
and easily replicatable. I do believe that the changes I have made have 
achieved this for those people who are actually committing. For example, 
today you can build all documents in the repos with a single command, 'make 
all'.

>
> > 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.

Agreed. Bazaar is perfect for our needs but then so is SVN. I don't really 
believe the problem is the technology platforms here. It's a human issue. 
Don't get me wrong, I know that can sound arrogant. But it's the truth, both 
systems can support the requirement I am suggesting. However, upgrade to 
newer SVN will create headaches for sysadmins and moving to bazaar will 
create headaches for the writers. It's a catch 22. Unless of course the 
writers are prepared to bite the bullet and go for it? If not then it will 
just have to wait.

-- 
Sean Wheller
Technical Author
sean at inwords.co.za
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050125/79c97adf/attachment.pgp>