Bit of a more general follow-up... I think it might be useful in trying to create some sort of policy for choosing thoughtful command names... I'm not sure how useful such a thing is, and I'm not a user interface expert by any means, but I am hoping I might have enough of a spark of passion here that it could be useful to darcs long term.
On 7/17/07, Eric Y. Kow <[EMAIL PROTECTED]> wrote:
I'm not sure how I feel about list. I'm slightly nervous about it being too 'similar' to the other commands (sorry, very vague), or it being too specific to things that can be listed.
I think specific in this case trumps vague. I think that ``query`` has always felt like a odds-n-ends bag of miscellanea. Can anyone describe what ``query`` is actually for other than as a place to put other "information" commands? ``query`` in this case is pretty useless semantically as a name and doesn't offer much in the way of how to use darcs. (In addition to being a 5 letter word with the ugly 'qu' at the beginning.) As a word, 'query' sounds needlessly academic in an otherwise "humane" command list. What I think ``list`` has to offer over ``query`` is a paradigm/strategy that is intuitively semantic. By pushing for ``list some-noun`` as a strategy it yields a simple goal-oriented approach to darcs, and tells us just from the English language usage a lot about what we might expect list to do and what might might expect to find as noun-subcommands to it. From a new user perspective: I want to get some "thing" from darcs. ``darcs list`` gives me lists of "darcs things". Does ``darcs list`` have the thing I'm looking for? I think that super-commands should have a modus operandi, a paradigm, because we are asking the user (even if it is ourselves) to add the additional level of indirection to their thinking and that level of indirection should be as helpful as possible. Rhetorical questions: What do you expect to be sub-commands of ``query``? ``list``? If you need to do some specific action how do you know to look under ``query``? ``list``? Suppose other super-commands existed and I gave you the name of a query sub-command how would you know to find it under query? Instead, if I gave you a noun related to darcs, wouldn't you immediately wonder if is "listable"? So, Eric, you become correct in that if we open the flood gates for some duplication where the set of goal-oriented "list a darcs thing" intersects with existing commands. Obviously that is something to consider, but I don't think duplication is necessarily evil; instead I think the duplication we see arise becomes our friend... What's the difference between a ``darcs list patches`` and a ``darcs changes``? I think the better question becomes what's the mindset that might cause someone to use one over the other. If I'm new to darcs and I'm told by a friend to see if I have the "Foo x in bar" patch from 3 weeks ago, there is a necessary mental leap that the noun ``changes`` at the top level implies that it "shows patches", whereas ``list patches`` sounds just about obvious what it does and how... Admittedly a trivial example as ``changes`` is one of the first commands that people learn, but the illustration I think is useful enough. A better example is probably something like ``list patch-content``. The goal: give me the dpatch (or contents) of a given patch without me having to scavenge in _darcs/patches/. ``list patch-content`` is inferable from the goal. ``darcs annotate`` isn't necessarily. In fact, I wouldn't know ``annotate`` did that if I hadn't asked on darcs-users some time ago. ``darcs annotate --help`` could enlighten someone that it did that, but not ``darcs help``. With just the goal in mind, iterating through ``darcs help``, would you think to give ``darcs annotate --help`` a try? But "duplicating" that functionality might not necessarily mean that annotate's ability to do the same thing should vanish. A newbie may easily discover the nested list command and a darcs veteran may take the time to learn that ``darcs ann --match='hash ...'`` does the same thing and does it with less typing. ``darcs list patch-content --help`` could even say that. Same goes for terse unix-style top-level aliases and discoverable sub-commands: one can be found when searching for a need and the other can be learned over time when aiming for "efficiency". Does all of this make sense? I think that English-language semantics play a large part in how easy to use a CLI program is, and there are many good reasons to make even "sub-command buckets" have some meaning and to keep that meaning in mind as you evolve the command "language" that the program speaks. -- --Max Battcher-- http://www.worldmaker.net/ _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
