scenarios + workflows + docs

[Karl Fogel]

Emma Jane Hogbin <emmajane at ubuntu.com> writes:
> I'd love to take a crack at this!

Great!  I don't know how much I'll be able to do actual writing, but I
can stay involved in terms of watching and kibbitzing (if you want).

> The way I've been picturing it is to start a page that has only the
> simplified graphics from the workflows (only the people/computers
> showing) with a brief text description). And then you choose the right
> picture for your needs and click through to the options for that
> picture. The options for each might be:
> 1. Extended description for this workflow (the scenarios?)
> 2. "In five minutes" mini tutorial to set up this workflow from scratch.
> 3. Converting to this workflow from other VCSes (e.g. centralized would
> have links for info on switching from CVS and svn).

Perfect, yes.  Now that you frame it that way, it's hard to imagine any
other way to go, actually :-).

Yes, I think (1) corresponds to the scenarios.  We can get rid of the
word "scenarios" of course: all that matters is that users find them,
not that they be called something in particular.

One possible issue is that the differences between some of the scenarios
are not easily expressible visually.  For example, the way to use bzr to
make a one-off patch contribution to some random open source project is
different from the way to use it to become a regular contributor --
that's why the first two scenarios are not the same.

Sometimes I wish those two could be unified, such that bzr (or a plugin)
would offer a single command that means "Set me up to follow PROJ and
maybe contribute patches".  As in:

   bzr init-repo PROJ
   cd PROJ
   bzr branch URL-TO-PROJ-MAINLINE PROJ-trunk
   [edit PROJ-trunk/.bzr/branch/config appropriately]
   bzr bind URL-TO-PROJ-MAINLINE PROJ-trunk
   bzr branch PROJ-trunk PROJ-dev

However, that's a separate issue.  For now, let's just document it...

> Do you know if there are source files for the workflow images? I've
> poked around the Wiki but I haven't found them. If not I'll just save
> them individually and hack away at them.>.

I don't know.  Ian Clatworthy might know, though.

> Generally speaking I find the plugins aren't well integrated into the
> current documentation and it's really difficult to know if/how you even
> want to use any of the plugins. This might just be a matter of creating
> new workflow graphics, but I'd be delighted to kick around new ideas on
> how we could make the plugins summary page [1] more useful to new users
> as well.

Regarding your last point: amen!  I just rewrote the BzrPlugins page,
incorporating all the information that was on UsingPlugins, and in
general trying to organize things a bit better.  Further improvements
welcome, of course.

However: I don't think it should be a goal to integrate the plugin
system into our documentation.  

For users, the whole concept of plugins is an implementation detail.
Users just want to know "How do I do foo in bzr?", not "How many
different tools are available on this Swiss Army knife?"  So we should
talk about plugins only in the context of "This plugin over here is how
you do foo.", not "There's this great system called 'plugins' and you'll
be so glad to learn all about it!" :-)

-Karl