Re: as promised, docs: git for the confused

From: Petr Baudis <pasky@suse.cz>
Date: Dec 9, 2005, 09:43 UTC
Message-ID: <20051209094328.GT22159@pasky.or.cz>
In-Reply-To: <20051209054304.3908.qmail@science.horizon.com>

  BTW, such a "wide" reply is a bit hard to handle - it might be perhaps
more practical to make separate replies at least to the mails whose
contents does not overlap. Also, people would not get Cc's of subthreads
they are not involved with.

Dear diary, on Fri, Dec 09, 2005 at 06:43:04AM CET, I got a letter where linux@horizon.com said that...

Show 14 quoted lines

> Finally, pasky@suse.de wrote:
> > That said, the "git for the confused" contains a lot of nice points, but
> > I don't think it's a good approach to just have extra document for
> > clarifying this stuff. It would be much better if the stock
> > documentation itself would not be confusing in the first place. Same
> > goes for the "commands overview" (BOUND to get out-of-date over time
> > since it's detached from the normal per-command documentation; we have
> > troubles huge enough to keep usage strings in sync, let alone the
> > manpages).
> 
> I don't think it's the ideal solution either, but the idea of trying to
> supplant Linus' tutorial is a bit alarming given my current still-novice
> state.  I've been dabbling with git for a few weeks; many of the people
> on this list have been using git in earnest for most of its life.

Now that's precisely what's most precious on you :-) - you have a fresh perspective (and you don't seem to appear as a bad writer, at least to me), actually much more important that technical correctness especially for non-reference documentation like this; we'll catch possible inaccuracies while reviewing, that's the least thing.

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

Now, having a task-based structured documentation (also called "user manual" ;-) is an entirely different story and yes, that would be extremely useful.

-- 
				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.