Re: as promised, docs: git for the confused

[Petr Baudis <pasky@suse.cz>]

Dear diary, on Fri, Dec 09, 2005 at 03:01:23PM CET, I got a letter
where linux@horizon.com said that...
> >> 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.