[RFC] Concise vs comprehensive help - do we need both?

[Ian Clatworthy]

It sounds like there are competing needs w.r.t. our on-line
help system:

1. I expect help to be comprehensive, particularly for
   key commands like branch, commit, log, merge and send.

2. John would rather 'bzr help xxx' where xxx is a command
   to be concise, around one page say.

I want comprehensive help because:

1. We need to do a better job explaining what Bazaar can do
   and in the case of commands at least, what better place
   is there than the help for that command? Calling up the
   help for a command only to be pointed somewhere else for
   more *reference* information on that command sounds wrong
   to me.

2. Following the DRY (Don't Repeat Youself) principle, our
   User Reference is built from the online help so that the
   two are always in sync. I feel very strongly that the
   User Reference ought to be *the* place that comprehensively
   documents what Bazaar is. The User Guide can and ought to
   explain the basic processes (how), including the mental
   model behind the design (why), but it shouldn't contain
   more information about what Bazaar is than the Reference.
   (This issue has been raised on the mailing list before.)

FWIW, my enhanced log help is 3-4 pages in length. *I* don't
think that's excessive when compared to other tools:

* svn - 1 page online and 4 pages in the book
* hg - 1 page
* git - 25 pages (!!)

OTOH, I can certainly see the need for concise online help.
Experienced users typically *just* want to be reminded about
what the options are and not see all the explanatory text.

So, I'd like to propose that:

* We continue to keep the User Reference and online help
  in sync

* "bzr help xxx" and "bzr xxx -h" give comprehensive help

* "bzr help -?" be supported & it should show just the one line
  summary and list the options.

Thoughts?

Ian C.