Short, task-based bzr doclets for real-world use cases.

[Neil Martinsen-Burrell]

Karl Fogel <karl.fogel <at> canonical.com> writes:

> 
> [This mail is long, because it's trying to get experts -- you -- to
> recall a long-vanished time when you knew nothing about bzr  .]

I remember it well.  Stepping up from "Woohoo I made a trivial branch" to
"I do my work in Bazaar" was a tall step.

> Tim Penhey and I were chatting about bzr adoption recently, and one
> thing we focused on was the bewildering array of choices a new bzr user
> faces.
> 
> Bzr's flexibility is a big problem for new users and prospective
> adopters: it means they have to absorb a lot of information before they
> can figure out what to do next.
> 
> This mail is about solving that problem by offering task-based
> documentation.  I survey existing documentation, and propose a way to
> make new task-based documentation.  But first, maybe a concrete example
> of the problem would help:
> 
> <example>

[...]

> </example>
> 
> I hope that example helped convey what a new user faces.
> 
> The fundamental problem here is a combination of two facts:
> 
>   1. Everything in bzr is done via branches.
>   2. Every potential branch comes with a bewildering set of choices.
> 
> Either of those alone would be okay; the two of them together create
> serious complexity.  If bzr is going to be so flexible, we probably need
> to offer firmer guidance about how to use it for particular scenarios.

I think a previous poster in the thread was correct that these two compound
difficulties are further compounded by user interface issues, where choosing 
the correct choices about how to use what kind of branches is not always the
most basic command (because there is not one obvious choice that should be 
the default).

[...]

> Seriously: everyone here has standard workflows they use for various
> tasks.  (Some of the workflows may disagree, but that's okay -- once a
> user is hooked, we can let them in on the secret that there's more than
> one way to do things.)  If I provide a seed list of scenarios, would
> people be willing to respond with short descriptions (a few paragraphs
> and exactly as many lines of command transcript as are needed) showing
> the workflow they would use to handle that scenario?  And of course, if
> you think of a common scenario not listed, just write it up.
> 
> Each one wouldn't take a lot of time.  Just do the scenarios you're
> confident you know how to handle, and send 'em in.  One editor -- any
> volunteers? -- would collect them, organize them, and reorient the bzr
> home page to lead new users to these documents.  (I'm going to hand-wave
> on that a bit right now, because the site needs to be considered
> holistically of course.)

Sign me up.  There've been a handful of mailing list messages that had 
similar explanations of "This is how I use the wonderfully flexible tool 
set that Bazaar provides to actually get work done."  Jon Arbash Meinel 
had a classic in that vein about using treeless checkouts and switch to 
manage many, many branches where the cost of building a new branch is high.

-Neil