presenting the fundamental abstractions

[Ian Clatworthy]

Matthew D. Fuller wrote:
> On Wed, Sep 05, 2007 at 03:04:15PM -0400 I heard the voice of
> John Yates, and lo! it spake thus:
>> This is the clearest statement I have seen of this.  Sadly Martin
>> stops short of enumerating those three components.  At present I am
>> unaware of any introductory bzr documentation that presents such a
>> picture.  Instead the documentation presents a panoply of composites
>> and a set of scenarios that may guide one towards a selection.
> 
> FWIW, I agree with this, and it always seems to me that people 'get'
> bzr and the meaning/use of the different composites much better once
> they grok the 3 components.  It also makes it much easier to explain
> things like "I just merged, why do I need to commit", and "I pushed,
> how come I still see the old files on the server" and so forth, when
> you can describe what components various activities affect.
> 

Easily the best I've seen of the various DVCS manuals in this regard is
Monotone. Chapter 1 of their User Guide is "Concepts". I believe the URL
is http://monotone.ca/monotone.pdf. If you can't get there (as I can't
right now), I've put a copy up here:
http://people.ubuntu.com/~ianc/vcs/monotone.pdf.

In comparison, I was a bit disappointed when I first read chapter 4 of
the Hg manual. It was certainly useful material but I felt it jumped
straight to the physical disk storage instead of covering logical
concepts enough first. For many potential DVCS users, particularly
non-programmers, it was too low level IMO.

> I've had sketches of a Handbook floating around in my head for 10
> versions or so, though not the time to get 'em on disk.  And covering
> those concepts has always been the first chapter to get through.

I've love to see our User Guide (http://bazaar-vcs.org/BzrUserGuide for
the draft) have a topic called Concepts in the Introduction section.

> There's a lot to be said for having a UI clean enough to not worry
> about the nuts and bolts of a system.  But I think this is a totally
> different question than that.  There's a difference between item
> implementation and conceptual structure.  It's nigh on impossible to
> use any tool if you don't understand the concepts its working with;

That's exactly right.

Any possibility of getting the ball rolling by getting your concept
thoughts onto a Wiki page, Matthew? We might be able to reuse some of
the Montone material, particularly their diagrams. (Their manual is
licensed under GNU FDL.)

Ian C.