[darcs-users] should 'changes' be renamed 'log'? (was: Re:SchwernLikesDarcs SchwernHatesDarcs)

[Michael G Schwern]

On Sun, Mar 20, 2005 at 02:46:34PM -0500, Michael Conrad wrote:
> > The overview of commands needs some love, thats true; also every new tool
> > takes some time to learn.  Fooling our users into believing its a drop in
> > replacement for cvs/svn is certainly going against everything a usability
> > person should be aware about..  Imagine: "The commands are the same, but
> > it does different things!"
> 
> I would point out that when using a new tool, it is reasonable to read the
> manual first so long as the manual is very very short, especially when the
> tool is going to do something that you rely heavily on (like archiving your
> data).  Especially if the tool operates differently than any others.

That is very reasonable.  However, large quantities of users will not
carefully study help screens.  I didn't. :)  Its frustrating but its a known
behavior.  You can scream RTFM! or you can design with user behavior in mind.

PS  darcs really isn't all that different from CVS, to me anyway.  Maybe
I've already been trained by SVK.


> Having said that, I do agree that people might not immediately associate
> "list of changes between revisions" with "changelog".  I wouldn't object to
> renaming 'changes' to 'changelog', or maybe just changing the brief
> description to "Gives a changelog for the repo in a human-readable format".

Yes, that would help.  Though perhaps drop the "human-readable" part.  The
user already expects that, unless stated otherwise, commands will output
in a human readable format.  I get the feeling that the "human-readable"
bit is really a more prideful "human-readable compared to most other 
version control systems".

Another way to look at it... if it states that this command gives a human-
readable changelog, specifically mentioning that otherwise obvious bit of
information can lead one to believe that there is a command which gives a
change log in a machine-readable format.  AFAIK the only thing which does
this is also "changes".