Re: [Monotone-devel] Why?

[Nathaniel Smith]

On Mon, May 30, 2005 at 05:12:14PM +0200, Richard Levitte - VMS Whacker wrote:
>      : ; ./monotone checkout --help
>      Usage: monotone [OPTION...] command [ARGS...]
>      [...]
>      Options specific to 'monotone checkout':
>        -b, --branch=STRING       select branch cert for operation
>        -r, --revision=STRING     select revision id for operation
>      
>           checkout [DIRECTORY]
>             check out revision from database into directory

This actually seems somewhat less clear to me.  Checks out a revision?
What revision, am I supposed to give a hex directory name or
something?  Oh, wait, there are some little generic-sounding things
tucked up in the big blob of text that I don't read, because it's
always the same... and seems like every command says "-b" and "-r"
anyway, so my eyes have learned to automatically ignore those too...

Obviously we don't want to duplicate everything in both the options
summary and the synopsis, but it does seem valuable for the synopsis
to contain the basic information critical to normal usage of the
command.  So, maybe it's a case-by-case judgement call, but a little
bit of appropriate redundancy can help readers, in general... and it's
nice if the synopsis can tell a coherent single-line story...

I kind of like it for 'update' as well, since people are likely to
have an expectation there that you _can't_ update to an arbitrary
revision, and are again very likely to miss that tucked up into the
option summary above...  Haven't thought much about the other
commands.

Or, you know, maybe my intuition is just weird.  Bikeshed time: anyone
else have an opinion on what's most user-friendly here?

-- Nathaniel

-- 
"On arrival in my ward I was immediately served with lunch. `This is
what you ordered yesterday.' I pointed out that I had just arrived,
only to be told: `This is what your bed ordered.'"
  -- Letter to the Editor, The Times, September 2000