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

[Paul Moore]

2009/1/16 Karl Fogel <karl.fogel at canonical.com>:
> [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'm not an expert, just a lurker who worked a bit with bzr but then
found Mercurial more to his taste. But some of my reasons *why* I did
so mirror your comments, so I thought I'd chip in. I hope that's OK -
I don't mean to troll.

> This turns out not to have been the best way to organize things :-).

That in itself is an issue. In my view, the "natural" way for a new
user to work (ie., the one he stumbles on without needing help from
experts) should be correct (at least acceptable, if not optimal).

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

3. Non-obvious approaches are correct; the obvious ones are sometimes
severely suboptimal. (The hugely over-used example of needing a shared
repo for performance, rather than a standalone branch, which is the
"obvious" approach, is the canonical example here; your example above
is another).

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

Publicly work on a bugfix for a project which doesn't use bzr (where
you are ultimately sending in patches)

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

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

Maybe also the question should be asked - *why* are task-based guides
needed? Flexibility, in and of itself, isn't the reason - just because
there's a lot of options, doesn't mean the correct one in a given
situation shouldn't be easily discoverable. But maybe it's too late to
address that one.

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

It's definitely a real problem. And your suggestion is an extremely good one.

Paul.