Theodore Tso wrote:
quoted text
> On Sun, Nov 11, 2007 at 10:50:26PM +0000, Johannes Schindelin wrote:
>> I beg to differ.  The biggest problem with a new user seeing all those 
>> completions is that this user is scared.
> 
> Well, if we introduce the new user only to "git subcomand", and the
> documentation is relatively gentle, I would suspect would solve most
> of the problem.  Note BTW, that if your thesis is true, "git help -a"
> (which is recommended in the last line of output by "git help") should
> cause the typical new user to faint dead away.  :-)
> 
> Some other areas that would be worth fixing, in terms of user usability.
> 
> 1) The references to the tutorial, everyday git, etc., don't actually
> have working references in the git man page.  (i.e., what you see when
> you run the command "man git").   It would be nice if that were fixed.
> 
> 2) The command which are displayed by "git help" should use some
> serious rethinking.  Ideally, it would be nice if the output fit in a
> single 24-line terminal window.   Some candidates for removal:
> 
>        a) prune: "git prune" definitely doesn't deserve to be on the
>        front and center as displayed by "git help".  Maybe replace it
>        with "gc", but now that we have gc.auto, I'm not sure it's
>        worth it at all.
> 

prune is definitely scary, and users don't need to know about it until
they've worked with git for quite some time.

quoted text
>        b) revert:  Is that really that common of a command?
> 

I think I've used it once ;-)

quoted text
>        c) show-branch: The output is terrifying without explanation
> 

Indeed. I still don't grok it fully. I tend to use gitk/qgit and some
brainpower to obtain the same result.


quoted text
> There are other commands I'm not so sure about, but it is worth
> flagging them.  One way that might be helpful is to group the commands
> into subcommands, much like gdb does, so you could do something like
> "git help other-repos" (where all commands that involve interacting
> with other repositories are summarized), and so on.
> 

Ack on that. I suggested it a while back and it appears many liked the
idea. I'm really bad at writing docs though, so it's one of those things
I've been putting off for "some other day".


quoted text
>> But yes, I was only proposing to deprecate all usage of git-<bla> in the 
>> documentation.
> 
> I agree that de-emphasizing git-<blah> isn't a bad thing.  But I think
> we need to look at the big picture here, since "git help" is often one
> of the first things a new user might try (and obviously very few git
> developers look at it, or "prune" probably would have been removed
> from git help a long time ago :-), and the last thing that git help
> suggests (and so therefore it will very visible to the newbie user),
> is "git help -a" --- and that displays every single git command under
> creation, porcelain or plumbing, in one gigantic sorted list.  
> 
> Oops, so much for first impressions.  :-)
> 

I agree. Culling the list output by "git help -a" to only show the
porcelain commands would definitely be worthwhile. I'm not sure if it's
worth having a way of showing every installed git command at all (I
know I've never used it anyway).

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html