RE: Suggestion: doc restructuring [was: Re: Considering teaching plumbing to users harmful]

["Craig L. Ching" <cching@mqsoftware.com>]

> -----Original Message-----
> From: git-owner@vger.kernel.org 
> [mailto:git-owner@vger.kernel.org] On Behalf Of Jon Loeliger
> Sent: Friday, July 18, 2008 1:26 PM
> To: Michael J Gruber
> Cc: git@vger.kernel.org
> Subject: Re: Suggestion: doc restructuring [was: Re: 
> Considering teaching plumbing to users harmful]
> 
> I always have to painfully search the page for it instead.
> 
I don't want to complain too loudly because I don't think I have any
good solutions, maybe yours is a good one, having an alphabetized list
of commands.  What I wanted to second, though, was that I too use the
browser search for all of the Git pages and that indicates that
*something* isn't optimal.

One easy thing I could suggest, and I'd be willing to try submitting
some patches if people agreed it's a valuable change (at least that's
something I think I could handle contributing for now ;-) ) is that when
you hit the "Documentation" link off the main page, instead of going
straight to the Man page, maybe it should go to a page that clearly has
the options that people are looking for.  E.g. a link to the tutorial, a
link to the man page, a link to the Git User's manual, a link to the
FAQ, a link to the "Git for SVN Users" page, etc.  The way it is now,
once you're used to the html rendered man page, it's not hard, but I do
think it's not the most newbie friendly way to navigate the
documentation atm.  Or maybe just feature those links more prominently
at the top of the man page so they're dead easy to spot.  Just my $0.02.
If someone definitively says what should be done, I'd be willing to give
it a shot.

> I'm not saying get rid of the Categorical organization.
> I am saying, we need a first-page with a straight, 
> alphabetized command index somewhere easy and located conveniently.
> 
> Thanks for listening,
> jdl
> --
> 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
> 

Cheers,
Craig