Re: Git Documentation

[Johan Herland <johan@herland.net>]

On Tuesday 22 July 2008, Scott Chacon wrote:
> If anyone has any tips on how they think git should be taught, issues
> they are asked a lot, problems newbies tend to have, something they
> wish there were a screencast for or was better documented, etc -
> please do contact me so I can incorporate it.

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...)

> If anyone has any tips on how they think git should be taught...

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

-- 
Johan Herland, <johan@herland.net>
www.herland.net