Re: as promised, docs: git for the confused

From: Petr Baudis <pasky@suse.cz>
Date: Dec 9, 2005, 21:33 UTC
Message-ID: <20051209213335.GU22159@pasky.or.cz>
In-Reply-To: <20051209140123.3234.qmail@science.horizon.com>

Dear diary, on Fri, Dec 09, 2005 at 03:01:23PM CET, I got a letter where linux@horizon.com said that...

Show 13 quoted lines

> >> 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?"

Well, yes, that's the approach I advocate as well! It's precisely the "task-based structured documentation" I talked about.

But the command listing is something different, actually the opposite:

"See, you have all those commands A, B, C. And this is what you can do with them."

That's to say, the former requires a lot more effort and writing than the latter and the latter has its uses as well, although I still think the former is superior. :-)

> (BTW, don't you mean "whatis -w git\*"?)

$ whatis git git (7) - the stupid content tracker git-add (1) - Add files to the index file git-am (1) - Apply a series of patches in a mailbox

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
VI has two modes: the one in which it beeps and the one in which
it doesn't.