Documentation development infrastructure

[Sean Wheller]

On Wednesday 02 February 2005 10:13, Robert Collins wrote:
> On Tue, 2005-01-25 at 07:53 +0200, Sean Wheller wrote:
> > 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.
>
> Hi Sean,
>         I'm curious in what ways Bazaar will create headaches for the
> writers - we're keen to make the UI of Bazaar better and better. While it
> lends itself to distributed archives, it works fine with a single shared
> repository too.

Hi Rob,

Thanks for your message.

I think the problem is that people have just started to learn SVN and are now 
faced with having to learn a new system. Admittedly, Bazaar is easier than 
tla, but I think it's a psychological factor. Faced with a situation where 
both systems can accommodate our requirements people who already know SVN are 
not easily inclined to want to learn a new system. I guess this is not solely 
a consideration for the doc-team but all users in general. How to port users 
of one system to another?

A bit about our *my* requirement.
I wanted to implement a "vendor drop" of the GNOME docs which we can use at 
Ubuntu. We would then be able to build Ubuntu docs as a patch on this 
dependancy. Some stuff would remain unique to Ubuntu and some stuff would 
result in changes moving upstream to GNOME. Once we have this, we can 
consider the same practice with Debian upstream.

In terms of complexity. Implimenting vendor drops using tla mirrors is 
actually easier under tla that it is under SVN, it should therefore be the 
same for Bazaar. Most users won't have to worry about this level of 
complexity, so I think it is just a question of learning a new incantation 
system. The only way to overcome this, as I see it, is for writers to "bite 
the bullet," "take the plunge." Yet, getting people to do is easier said than 
done.:-)

One of the major organization problems we have is that there are many 
repositories and people are not always aware of where those repositories 
exist or what is contained in them. In practice, I believe we should all be 
working in the same place. In reality this is not the case. So, since for our 
purposes we are only interested in documentation, we would like to gather our 
'stuff' into a single place and build Ubuntu documents based on already 
available resources. This cuts our development time and enable us to focus on 
adding improvements and Ubuntu specific things.

An additional issue, as I see it, is that our writer group are great and 
knowledgeable about GNU/Linux and the Ubuntu Desktop, but are not technical 
in  the aspects of Docbook XML, XSL and revision control systems. Since these 
technologies do present a barrier to entry for the vast majority of people, 
it was decided that enabling people to use wiki would help. This of course 
creates a problem. Wiki is a sure way to mess up your document information 
and is not easily ported to Docbook XML. So, the user group in the doc-team 
may be an excellent profile for testing the usability aspects of Bazaar.

I realise this is not the focus of the Bazaar project, but faced with a user 
level such as I have described above, requires a simple install of Bazaar 
such as that of SVN under Windows and simple GUI front end. :-)

Hope this helps.


-- 
Sean Wheller
Technical Author
sean at inwords.co.za
084-854-9408
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/20050202/4c0b2bba/attachment.pgp>