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

[Karl Fogel]

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

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>

I decided to work on bzr bug #306394, partly to educate myself as a bzr
user.  I read what seemed to be the essential parts of the User Guide...

(The User Guide is fantastic, by the way.  This mail is not a criticism
of that document.  The Guide is thorough, impressively well-organized,
clearly written, has great diagrams, etc; it's obvious that someone put
real care into it.  But typically, a user will only make the investment
to read the User Guide *after* they've started using the tool already.
We need to make it easier for people to get to that point first -- once
they do, there's great documentation waiting for them.)

... anyway, having read up on the basics, I made a branch of the
mainline bzr repository (relying on memory here):

   $ cd ~/projects
   $ mkdir bzr
   $ cd bzr
   $ bzr branch http://bazaar-vcs.org/bzr/bzr.dev/
                ### (as an aside: why isn't this just "lp:bzr"?) ###

At this point, I wasn't sure what to do next.  Should I create a new
branch specifically for working on #306394, or should I work directly in
the branch I'd just created?  If I did create a new branch, should I do
it from the upstream branch, or from my local branch?  Was I supposed to
have run "bzr init" somewhere along the way?  Or "bzr init-repo"?

Well, I figured I could just make my changes in the new "bzr.dev" branch
I'd created locally, and periodically do "bzr merge; bzr commit" to
bring in upstream changes.  Since my local #306394 changes would be the
only difference between my branch and the mainstream, it would be easy
to pull them out later for submission to the project.  Or so I thought.

This turns out not to have been the best way to organize things :-).  My
theory was sort of correct, but my repeated "bzr merge; bzr commit"s
meant that I was creating unnecessary local changes.  What I really
wanted was (I think) to mirror upstream using "bzr pull", and create a
separate task branch for my work on #306394.  The recipe also involves
using 'bzr bind' and setting a public_branch in .bzr/config.

But I only found this out piecemeal, via help from other bzr developers:
see https://lists.ubuntu.com/archives/bazaar/2009q1/051490.html and the
responses to it.  I still haven't found a document anywhere that says
the things I was told in those responses, even though my scenario
(publicly working on a bugfix, with likelihood to do more of same) is
pretty common.

</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.

What I have in mind are short, task-based documents saying "Here's
exactly how you'd use bzr to do X", where X might be:

   - Start a new project in bzr (with intent to collaborate)
   - Maintain local changes against an upstream source over time
   - Publicly work on a bugfix for a project already in bzr
   - Publicly work on a bugfix for a project already in bzr (in Launchpad)
   - Publish my changes to project Foo, independently of Foo's maintainers
   - Cooperatively maintain a web site in bzr, with automatic updates
   - Accept changes from others, for review and incorporation into a
       mainline that you are responsible for
   - etc, etc (suggestions welcome)

These documents would *not* tell you all the options you have.  Instead
they'd give recipes: one set way to do it, with conceptual explanations
geared around the recipe, and footnote-style references leading out to
further documentation (such as the User Guide) for more depth.  But I
really think we need to keep that depth out of the user's face during
their initial adoption period -- nobody likes to go into a tunnel when
they can't see the other end and have no idea how long it might be.

I don't think we have much in the way of task-based guides right now.
What I've found are:

   * "Bazaar in five minutes"
     http://doc.bazaar-vcs.org/latest/en/mini-tutorial/index.html

   * "Bazaar in five minutes for web devs"
     http://bazaar-vcs.org/BazaarForWebDevs

   * "Bazaar User Guide"
     http://doc.bazaar-vcs.org/latest/en/user-guide/index.html

   * "Workflows"
     http://bazaar-vcs.org/Workflows

   * "Bazaar Switcher Guides (bzr for cvs users, bzr for svn users, etc)"
     http://bazaar-vcs.org/BzrSwitching

   * "Why Choose Bazaar?"
     http://bazaar-vcs.org/BzrWhy

   * "Introducing Bazaar"
     http://bazaar-vcs.org/Bzr

The first two kind of fit the bill.  Unfortunately, they have to spend a
lot of time on starting the project, whereas many new users are joining
existing projects -- perhaps project initialization is something we
should break out into a shared document?

Anyway, besides those two, the rest is conceptual documentation, in
which the command examples illustrate features of bzr rather than
solutions to problems.  I thought "Workflows" might be a candidate, but
its table of content shows that it is something else:

   1. Solo
   2. Partner
   3. Centralized
   4. Centralized with local commits
   5. Decentralized with shared mainline
   6. Decentralized with human gatekeeper
   7. Decentralized with automatic gatekeeper

That's useful for people who are already familiar with version control
concepts -- people whose mentality is already organized around the tool
rather than around the task.  But most newbies arrive thinking in terms
of the task, so that table of contents doesn't help much.  "Workflows"
is still a document for people who have already decided to make an
investment in learning bzr, not a document to persuade them to do so.

So how do we get more task-based documentation?

Well, it's 2009, so I guess crowdsourcing is the answer to everything :-).

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.)

Thoughts?  Rotten tomatos?  Am I onto a real problem here?

-Karl