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

[Ian Clatworthy]

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

Thanks for kicking this thread off. We need to do everything we can
to ease the migration to Bazaar. Having a natural UI and easy to
follow documentation path ways are essential pieces IMO.

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

As you and others have indicated in this thread, I don't believe
our "fix a bug on a project" model is simple enough yet. I'd like
it to be something more like:

  bzr clone lp:XXX
  cd XXX
  bzr branch trunk fix
  cd fix
  (hack, hack, hack)
  bzr send

The thinking behind this is that it's good if new developers
to a projects start in a way that the project's core team
have setup for this purpose. (They can always personalise
later via reconfigure once they have the expertise/desire to.)
See my "make clone intelligently DTRT" proposal explained in
https://bugs.launchpad.net/bzr/+bug/316729.

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

Thanks. I'll take some of the credit for that. :-) The User Guide got
some love just before 1.0 but hasn't really progressed much since.

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

I think part of the answer here is (strictly) one-page
"Bazaar for XXX users Quick Start" documents:

* column one is commonly used commands in XXX
* column two is the matching Bazaar command.

The migration wiki pages also need some serious love.

> I hope that example helped convey what a new user faces.

We "experts" consistently under appreciate it because it's
not an itch we need to scratch, bar supporting others on IRC say.
See http://www.infoq.com/presentations/Developing-Expertise-Dave-Thomas.
Right now, most DVCS adopters are already damn switched on, so
getting them going is *relatively* easy (vs when the masses of
Novices + Advanced Beginners *really* migrate from cvs/svn).

> I don't think we have much in the way of task-based guides right now.
...
> So how do we get more task-based documentation?

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

I think that would work. Writing when we're learning also produces
quite useful information for others in my experience. (Any errors
can be picked up by the experts during review so don't worry about
making the documents perfect before publishing them.)

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

I'll make another "make Bazaar's documentation better" surge in
coming months. Next time round though my focus will be more on
completeness than getting started, i.e. stuff like:

* upgrading the User Guide to cover important features
  added since 1.0, e.g. send
* making the User Reference more comprehensive, e.g.
  including the standard plugins
* writing the Admin Guide (it's just a TOC curently)

Right now though, I'm knee deep adding features I want
(EOL+keyword support, filtered views, better log) and
helping indirectly on the next fast format work.

Ian C.