08:16 < abentley> Better phrasing: 'what circumstances should cause us to produce a working tree in a repository branch'?

[Jari Aalto]

Denys Duchier <duchier at ps.uni-sb.de> writes:

> Aaron Bentley <aaron.bentley at utoronto.ca> writes:
>
> 	bzr create --repository --clone ../FOO
>
> It seems to me that advertising "bzr create" as the command to create things
> makes it cognitively simpler for the user.

Exactly. The smaller set the base commands, the better. It's like
an expanding there

       
       +--
   a --+--
       +--+--
       b  +--
          +--
          c

>From command (a) you select next level (b), and from there you select
(c) if needed. logical, simple to understand.

>> People don't like copious help.  They like direct, to-the-point help.
>
> I think you are overgeneralizing on your personal typical use case.
> People like terse help when they only wish to be reminded of
> something they already know, and more extensive help (especially
> including examples) when they either don't know or can't remember.
> Ok, I am not "people", but I know that's the case for me. So I'd
> probably like "bzr create -h" to print the terse help and "bzr
> create -h -l" to print the more extensive help.

I'm novice with bzr. I need all the help I can get. If the "help"
doesn't cut it, I must do lot of "googling" and interrupt my current
work, when the information is not sufficient. A good help page
consists of

     QUICK GUIDE / EXAMPLES
     ... with exampes  (gimme pictures :-)

     THE MANUAL

     The gory details

     TROUBLESHOOTING

The Unix man(1) pages have mostly forgetten the "EXAMPLES" and tend
to be too technical for average novices. Fortunately some of them
do take the "people en masse" into consideration, like in rsync(1).


Jari