Re: What have the Romans done for us? (Bazaar)

[Chad Brown]

On Apr 6, 2010, at 7:31 AM, Alan Mackenzie wrote:

?  http://doc.bazaar.canonical.com/en/ points to plenty of downloadable

documentation, in HTML, CHM, and PDF formats.

They all lack hyperlinks or are non-searchable.  (BTW, I'll need to find
out what CHM is).

It's an acronym for `Compiled Help file (Microsoft)' -- does that tell you 

everything you need to know? :-)

It's a format used to make HTML help file bundles for MS's `help viewer'.

You almost certainly don't care.

 But worst of all is the low quality of the reference
docs.  For example, 'bzr help merge' doesn't say with any specificity
what is being merged or where the result is written.  It talks about
"merging a branch", which makes as much sense as "the difference between
a file" does.  This vagueness is prevalent over much or all of 'bzr help
<cmd>'.  Is it too much to expect these man pages (in effect) to be
precise?

I don't disagree at all, but you might find it helpful to spend an hour or so

digging through

http://wiki.bazaar.canonical.com/BzrGlossary/

In general, the docs seem to assume that you're either already familiar with

vcs concepts and are just looking for the bzr keywords, or that you don't 

care at all and are just looking for the right set of magic words to say to 

avoid angering the wizards.  I suspect that the aim to cater to as many 

different `methodologies' (what we've been calling workflows on this list) 

has encouraged a doc style that's so detail-agnostic that it's hard to ever 

find useful content.

I hope that helps,

*Chad