[MERGE/RFC] Userdoc Driven Design on the Bazaar 2.0 UI

[Stephen J. Turnbull]

Ian Clatworthy writes:

 > And high on the list of things many of us want to see as part of
 > 2.0 is a gentler on-ramp for new users.
[...]
 > It's fine to add feature after feature over time but does the net
 > whole still make sense to new users?  Recently, we've been hearing
 > otherwise.

Here's an interesting statistic that appeared on the darcs-users list
yesterday or so (<49E5B12B.3080003 at theingots.org>; heavily edited):

    Most version control systems have around 60 commands (git has
    133). Darcs attains the same or better feature set with 32. Due to
    their clean and simple design, Darcs commands are easier to learn
    and easier to understand.

    When I counted the command set for Mercurial, SVN and Bazaar I got
    48, 56 and 62 resp. Only Git had more than 100 commands (it has 133).

While the claim about "same or better feature set" was retracted, I
think it's worth noting that Mercurial and git (especially the latter)
devote a large number of commands to manipulating the DAG.  In that
sense, Bazaar's feature set is closer to Darcs's than to Mercurial,
but it has 25% more commands than Darcs.  (Note that Bazaar's feature
set generally claims "better" versions of common commands---better
logging, better merging, etc.---rather than operations that aren't
present at all in other systems.  This is true even of stuff like
lightweight checkouts to a great extent.)

Note: this has *nothing* to do with the "actual quality" of Bazaar's
command set, but the Darcs folks definitely consider their low count
as a marketing plus.  And it is certainly true that new git users
complain of the plethora of commands that need to be triaged into
IAGNI, YAGNI, NAGNIE.[1]  So the number of lines in the command list
does count, both for marketing and for newbie confusion.

 > Both of these ideas came from Mark Shuttleworth, a rather big
 > fan of ours. :-) In the spirit of Userdoc Driven Design, Mark has
 > put together an excellent tutorial explaining checkouts, branches
 > and repositories to "2.0" users.

As an explanation of the status quo, I agree it's excellent.  As a
marketing tool, I'd say it highlights just how geeky Bazaar has
become.  It is quite clear from the tutorial that effective use of the
vaunted flexibility of bzr needs intimate knowledge of implementation
details.

But I don't understand *why* it's needed.

It seems to me that "bzr init-repo" is the kind of thing that users
should not need to know about, period.  The fine distinctions (or lack
of them) among branch, checkout, and clone, and merge, pull, and
update are confusing, especially since their semantics differ across
the various VCSes the user may have experience with. :-(

Footnotes: 
[1]  In case the expansions aren't obvious, that's "I Ain't Gonna Need
It", "Y'all Ain't Gonna Need It", and "Nobody Ain't Gonna Need It EVER".