Re: Git Documentation

On Tuesday 22 July 2008, Scott Chacon wrote:

You should at least take a look at this thread:

http://thread.gmane.org/gmane.comp.version-control.git/88698

(even though it goes off-topic after a while...)

It seems there are primarily two ways to teach Git:

1. Top-down: Start with simple use cases and commands. Teach people a 
minimal, but necessary set of porcelain commands to get them started. Stay 
_far_ away from plumbing commands and most of the command options.

2. Bottom-up: Start with how Git structures the data. Talk about blobs, 
trees, commits, refs, how everything is connected, and how various Git 
commands query and manipulate this structure. This _may_ involve a fair 
amount of plumbing commands, especially when discovering how the more 
complicated high-level commands manipulate the structure.

Some people seem to prefer the first approach, other people prefer the other approach. Both paths lead to enlightenment ;). In many cases a bit of both may be useful. HOWEVER, I think it is _very_ important to keep in mind that these are two _different_ approaches, and the contexts in which they are taught should be kept separate. I would almost suggest splitting your website down the middle and make the difference between top-down and bottom-up immediately visible with, say, a different background color, or something else that immediately tells the user what "track" they are following...

BTW, I think what you're doing is good and important (and I've already enjoyed some of your gitcasts). Keep up the good work! :)

Have fun!

...Johan