Re: [doc] User Manual Suggestion

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Apr 25, 2009, 10:35 UTC
Message-ID: <94a0d4530904250335w7a88c4d6lafd12a8ce6f98127@mail.gmail.com>
In-Reply-To: <20090424185208.GM17365@fieldses.org>

On Fri, Apr 24, 2009 at 9:52 PM, J. Bruce Fields <bfields@fieldses.org> wrote:

Show 13 quoted lines

> That would be great, thanks.  Several people have gone off and posted
> their own tutorials someplace, and that's fine, but it would be
> especially helpful if you could contribute to the actual Documentation/
> directory.  That may mean arguing with people and making compromises.
> But it also means the results will be distributed with git, will be
> integrated with other git documentation, and will get first-class
> technical review.
>
> I'd also encourage incrementally improving existing documentation where
> possible instead of starting over from scratch.  But having broken that
> rule myself a couple times I'm hardly in a position to insist.  If you
> must start over, at least think about how to replace or fit it in with
> existing documentation.

People will continue to write git documentation from scratch because there is a huge gap from the top-bottom approach to a point where you actually "get git", and people are trying to find short-cuts so that other people can really get it too.

I spent years using git simply repeating the templates I had seen in multiple places until I stumbled upon "git from the bottom up" and then I finally understood the beauty and simplicity of git's design. From that point I understood why many command didn't do what I expected.

Note that "bottom" doesn't mean plumbing, the "plumbing" is usually referred to the git.git tools, but you can work with git low-level objects through your own implementation as people like Scott Chacon have indeed done (git-ruby). "bottom" then means git basic building blocks: blobs, trees, commits, refs.

Ideally the UI should expose the basic concepts of git, but instead its is hiding them, so no wonder people *need* special documentation to 'understand git conceptually', or learn 'git from the bottom up', etc.

-- 
Felipe Contreras