Fwd: [Python-Dev] Primer on distributed revision control?

[Paul Moore]

On 25/03/2008, Paul Moore <p.f.moore at gmail.com> wrote:
> On 25/03/2008, Ian Clatworthy <ian.clatworthy at canonical.com> wrote:
>  > Any reason why you prefer the Hg book to the Bazaar User Guide?
>
> Honestly, I'm not entirely sure I can remember now how I formed that
>  impression. I'll reread both and see if I can be more concrete.

I've just reread the Bazaar guide this evening. I didn't reread the
Mercurial book. I haven't had time - it's too long. That's a key point
here - at 187 closely-spaced A4 pages, including a contents and index
vs. the Bazaar User Guide at 96 pages of chunky looking text with no
index and a contents section without page numbers[1], the Mercurial
book feels far more like a "real" reference book. I know that's just
look and feel, but it does make a difference.

With regard to writing style, I agree with Steven Turnbull - the
cheerful, nearly-smug style is fairly grating. (And the big, slightly
rounded font used, plus the cheery cartoon-style diagrams, reinforce
that impression, making it feel deliberate, rather than just an
unfortunate turn of phrase).

All of that is just style, and possibly reflects target audiences. I'm
looking for something more like a good guide - not a tutorial, but not
a reference manual. I much prefer written books, but am resigned to
the fact that very little software comes with real paper manuals any
more. But that's what I want - something that I can keep a printed
copy on my desk to refer to.

OK, enough on style, I'll try to describe my issues with content.

The section on core concepts is nice. But it has one glaring flaw,
which is as much a flaw with Bazaar terminology as with the manual -
none of the terms refer to anything *concrete*! I have a directory on
my disk - what do I call it? The guide doesn't give me a name I can
use[2]! In Mercurial, and hence in the Mercurial book, it's easy -
it's a "repository". End of story. That makes the whole of the text
flow far more cleanly. I find that's true when I'm writing about
Bazaar as well - it's hard to be concrete without either being verbose
or vague.

Another particular issue I have is with the "Workflows" section. A
large number of workflows are described, and yet *none* of them match
how I want to work! The Mercurial book concentrates on telling me what
tools I have, and leaving me to decide how to put them together.
(There are just as many problems with doing things this way, but it's
what *I* prefer). For what it's worth, the 2 ways I most often work
are (1) a variation on personal use, where I'm using 2 unconnected
machines (work and home) and a USB pen drive to sync between them
(merging is a more common operation that way, as I regularly forget to
sync before shutting down :-)) and (2) tracking an upstream project -
often using Subversion rather than Bazaar - where I do not have commit
access, and using my local Bazaar repository to develop patches for
sending back upstream usually as simple patch files. I don't expect
these workflows to be described, they are peculiar to me, but by
describing workflows rather than tools, the Bazaar guide (a) gives the
impression that my workflow is "less supported" and (b) doesn't give
enough details on the individual pieces I'll need to consider to build
my own workflow.

As a result of the focus on "standard" workflows, chapters 3-6 all
make me feel "no, this isn't the bit I'm looking for" - even if the
actual text describes individual tools that would be useful to me!

There is also a lack of lower-level detail. I know it's not
necessarily reasonable content for a "user guide", and I'm not sure
the placement of it in the Mercurial book is right, but the chapter on
"Behind the Scenes" in the Mercurial book is really nice to have.

I'm sorry - this ended up being far more negative than I had wanted.
It's a hard, thankless task producing documentation, and the work you
(Ian) have done improving the Bazaar documentation is hugely valuable,
and should not be ignored. Much of what I say above reflects my
personal prejudices, and should be taken as such. I actually don't
think I'm a good example of the target audience at which the Bazaar
User Guide is aimed, so it's not surprising that I don't find it as
satisfying as others might.

I hope this is of some use.

Paul.

[1] I know some of that is simply because one is in PDF where the other is HTML.
[2] Specifically, it depends on if it's under a shared repository, or
it *is* a shared repository, or it's a separate branch (standalone
tree?) or a checkout (heavyweight or lightweight). But sometimes it's
just a directory of files managed by Bazaar... Too many choices can be
as bad as none.

PS I see that Stephen Turnbull and John Yates have also provided
fairly detailed responses. I haven't had time to read them properly
yet, but I will do so and see if I have anything further to add based
on their comments.