Usage of bzr-hg plug-in

[Ben Finney]

Jelmer Vernooij <jelmer at samba.org> writes:

> So what is it that you think should be documented but is not at the
> moment? Should we point at the main bzr documentation and explain
> that is relevant ?

In general: The help documentation for third-party plug-in “foo”
should answer the question “Now that I have installed ‘foo’, what has
changed, and how does that affect me?”

The documentation for ‘bzr-hg’ gives a vague answer to the first part
(but doesn't help if I don't know what “support for Mercurial file
formats” actually means to me in using it), and nothing on the latter
part.

> Ben Finney wrote:
> > I concur with Colin that documentation online is very desirable
> > *before* downloading any package, to decide whether it serves
> > one's purpose and what will be needed to begin using it.
> Well, this is stretching "documentation" a bit imho.

Why so? Before installing Bazaar, I browsed its online user manual.
The fact that I could do so weighed heavily in its favour when making
the decision to install.

> The bzr-hg description currently says:
> 
> A plugin for bzr which provides support for Mercurial file formats.

As a user, I don't care about “for Mercurial file formats”; that's
implementation-level talk. I want support for *doing* things that I
couldn't do before, and this sentence doesn't make it clear how “file
formats” relates to that.

> It currently allows pulling from (and eventually pushing to) hg
> repositories.

Sounds great, but there's no clue *what to do differently* now that
this ability has been asserted. Refer back to my original message in
this thread for what I was led to assume would be the case.

> Anyway, if you suggestions about how to improve this description,
> they're welcome.

Thank you for continuing to ask for feedback.

I don't know how to word it, but I would expect a UI-level answer to
the questions “What can I do now that I couldn't before?” and “How
should I do it?” If that's as simple as telling me which *existing*
commands now work differently (and how they work differently), then
that's what to say.

-- 
 \             “The greater the artist, the greater the doubt; perfect |
  `\       confidence is granted to the less talented as a consolation |
_o__)                                           prize.” —Robert Hughes |
Ben Finney