From: Felipe Contreras Date: Sat, 25 Apr 2009 10:35:38 GMT Subject: Re: [doc] User Manual Suggestion 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 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