Re: [doc] User Manual Suggestion

[Felipe Contreras <felipe.contreras@gmail.com>]

On Fri, Apr 24, 2009 at 9:52 PM, J. Bruce Fields <bfields@fieldses.org> wrote:
> 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