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

[Ben Finney]

"Stephen J. Turnbull" <stephen at xemacs.org> writes:

> Karl Fogel writes:
> 
>  > We can have pointers to it, tantalizing footnotes that say things
>  > like "If you're planning to be a regular contributor to project
>  > foo, then you can set things up in a more efficient way -- see
>  > <HERE> for details."
> 
> I don't think that's a good idea. I (for one) don't find such
> footnotes tantalizing, I find them foreboding.

I think the fact that the “quick setup just for a bug fix” scenario
*must* at least mention that it's deliberately choosing a
less-efficient configuration in the interest of simplicity.

At least that way, if the user notices the performance is rather
lagging compared to $OTHER_VCS, they have a decent chance of
remembering that special note was made of this in the quick setup
guide.

Otherwise, I can only see such a document setting newbies up to
confirm the “Bazaar is slow, just like everyone keeps saying” meme —
and at that point, we will lose a significant proportion of
prospective users *forever*, because most people will not re-visit
their initial conclusions.

First impressions matter. If we deliberately choose to make the first
impression a poor-performance one (by a procedure for first-time users
that sets it up that way), we need to combat that impression as
directly as we can.

-- 
 \          “Better not take a dog on the space shuttle, because if he |
  `\   sticks his head out when you're coming home his face might burn |
_o__)                                                up.” —Jack Handey |
Ben Finney