scenarios + workflows + docs

[Ian Clatworthy]

Karl Fogel wrote:
> Emma Jane Hogbin <emmajane at ubuntu.com> writes:

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

They're in the bzr source tree:

  bzr branch lp:bzr
  cd doc/en/user-guide/images

Or grab them directly from Loggerhead:
http://bazaar.launchpad.net/~bzr/bzr/trunk/files/head%3A/doc/en/user-guide/images/.
The svg images are the master.

If you do make improvements, please consider submitting them back via
a patch to the bzr source tree so we can use the better versions in the
User Guide and other standard docs.

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

Ditto. We could do so much better, e.g. something like the extensions
page for FireFox that shows the most popular and highly ranked plugins
would be neat.

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

Precisely.

I do want to extend the User Reference to include reference docs for
the *standard* plugins that ship as part of the core. Otherwise, my
approach to date has been to reference plugins as they make sense
throughout the User Guide. Larger plugins like bzr-svn really need
their own section though.

Ian C.