Re: GIT vs Other: Need argument

["J. Bruce Fields" <bfields@fieldses.org>]

On Tue, Apr 24, 2007 at 08:01:50AM -0700, Linus Torvalds wrote:
> Well, I think they really should be documents of their own, so that you 
> can read about the "CVS tracking" or so without even worrying about the 
> fact that you didn't read the whole thing.

Sure.  There may be some tension between making more separate documents
and keeping them all findable.  Well, it just means we need some easy
way to index them.

> And they should be easy to find. I agree that we do actually have a fair 
> amount of docs, but it seems that people don't tend to *find* them. The 
> user-manual, for example, is great, but I've seen people on the #git logs 
> apparently not realize it exists ;)
> 
> For example, the git homepage has a "documentation" thing, which only 
> lists the tutorial, not the user manual explicitly. You _can_ get to the 
> user manual (go to the online version of the Documentation directory and 
> note the "still work in progress"), but even if you do actually find 
> yourself there, the user manual itself is actually a bit scary to start 
> with.
> 
> So I think we could just make the initial impression a bit easier. The 
> tutorial comes fairly close to the "tracking your own" thing, I agree, 
> but maybe we could have the documentation listed in order of complexity, 
> and having a way for people to know *which* doc they should start with 
> when they are at http://git.or.cz/ (or the wikipedia page), so that if 
> you're only interested in the "tracking somebody else", you could easily 
> find and read just a single simple documentation thing. Hmm?

Yeah.  So we can try to figure out a small set of clearly labeled entry
points into the documentation, and I'll work with Petr Baudis to make
sure they're at the top of the git home page.  And I suppose the same
set should appear on the main git man page.  Anywhere else?  Maybe
Documentation/ needs its own index.html....

--b.