Re: as promised, docs: git for the confused

On Fri, 9 Dec 2005 linux@horizon.com wrote:

> >> Unfortunately, given the number of commands, you can't just document
> >> them well individually.  Some overview of how they fit together into
> >> a system is required.
>
> > Hmm. Well, actually... what's the point? If I want to get a really quick
> > overview, I do
> >
> >	whatis git
> >
> > and it will DTRT. But when do I need something more detailed but not yet
> > the manual page of the given command?
>
> "I want to do X and Y but not Z.  What commands are worth knowing?"

I agree big time.  Even for quilt (about 30 commands),
I wrote a summary (cheat sheet) of usage models:

a.  making a new patch:  use this series of commands
b.  importing patches:  use this other series of commands
c.  other patch management commands


> I have 106 git-* commands available to me (my document covers 105;
> I'll have to find the extra), and the biggest question I have is
> "how many of those man pages can I get away with NOT reading?"
>
> Heck, that categorized list is what I started out writing, and I happen
> to think it's the most important part of the whole document.
>
> The man page tells me HOW to execute a command.  But before I'm ready for
> that level of detail, I need to figure out WHICH command to execute.
> To be specific, I need to know the terrain just well enough so I can
> plan a route from where I am to where I want to be.  Then I can look
> into the details of each step.
>
> But without that overview, my trip is going to take me into a lot of dead
> ends, because I'm executing commands that I think are getting me closer,
> but I have the wrong mental model of what "close" is.

-- 
~Randy
-
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