Usage of bzr-hg plug-in

[Jelmer Vernooij]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ben Finney wrote:
> Jelmer Vernooij <jelmer at vernstok.nl> writes:
>> On Tue, Mar 10, 2009 at 07:05:33PM +1100, Ben Finney wrote:
>>> The ‘bzr-hg’ plugin <URL:https://launchpad.net/bzr-hg/> doesn't give
>>> much information on how to use it. 
>> Similarly to bzr-git and bzr-svn, it will allow access to Mercurial
>> repositories from Bazaar. The existing documentation for Bazaar should
>> be sufficient here, as bzr-hg doesn't provide anything visible in the
>> UI of Bazaar.
> 
> No, the existing documentation is not sufficient. Knowing very little
> about how the plug-in might operate, and having failed to find any
> documentation on the website before downloading it, I have installed a
> plug-in, for which there is a brief help message that is strangely
> detailed about implementation limitations but entirely devoid of how
> to use it.
I agree that the description shouldn't mention that sort of details.

> Having installed it, with a vague idea of what its purpose might be, I
> then have nothing to tell me what to do next. The original message
> shows where I, personally, was expecting to find such information;
> maybe other non-Bazaar-developers will have different viewpoints.
> 
> Since I came to the end of that quest — rather longer than I might
> spend on most programs similarly undocumented — without knowing what
> to do with it, I don't consider the existing documentation sufficient.
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 ?

>>> (Is there a place at Launchpad where the documentation for a
>>> package is stored? Or does Launchpad not encourage standard
>>> documentation for packages?)
>> Not sure I follow, if there would be more documentation necessary it
>> wouldn't be on Launchpad but inside of the package itself. Similar
>> to e.g. alioth.
> 
> 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. I agree there
should be a proper description of what a plugin is on the launchpad page.

The bzr-hg description currently says:

A plugin for bzr which provides support for Mercurial file formats. It
currently allows pulling from (and eventually pushing to) hg repositories.

which seems sufficient to me, even if it is a bit short. Anyway, if you
suggestions about how to improve this description, they're welcome.

Cheers,

Jelmer
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iJwEAQECAAYFAkm5ZVIACgkQDLQl4QYPZuVjKAP+KSRkbqbwoVDd0MQiW3oTKWpG
b4q2IymcCwe3Q0Z/fb8Oei2NrVAUIJgK2uqJOiiq2n+Liu/TR9XwwhLX6RSDPkGC
LlybRLeQDYx8EUNz4icL++1CZGcS+kDax4xnFoKf0+J59xNTuGzSBocyOzHpU/hx
p2FVAWLKiDk/6GyuSf0=
=TxGB
-----END PGP SIGNATURE-----