On Tuesday 22 July 2008, david@xxxxxxx wrote: > On Tue, 22 Jul 2008, Johan Herland wrote: > > 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... > > possibly a combination of the two? > > under the covers the git data-structures are pretty simple and explaining > them (and the minimal tools to manipulate them) isn't that bad. Not sure. In both cases one will need _some_ kind of model to work with, but I think that for the top-down approach, it will suffice with a very simple/simplified model along the lines of: - A commit contains the state of some repo at some point in time (plus some metadata) - A commit points to its direct parents (zero or more). A collection of commits make up a DAG, representing the history of a project. - Refs point to select commits. Tags are static, branches are dynamic, etc. Specifically, for the top-down approach I do NOT think it is necessary to teach: - blobs and trees - plumbing tools > what gets ugly is when you then try to use the plumbing to do the > non-trivial things. Certainly. We should only use plumbing tools in the bottom-up approach, and even then we should only use them when it _simplifies_ or otherwise nicely _illustrates_ the concepts being taught. > so how about an optional 'under the covers' primer, covering just the > trivial plumbing, then the high-level minimal introduction with a link on > each of the commands as they are introduced (so that a person can dig > into deeper detail if they want to, possibly including 'up until version > X this command was implemented by the following script'), followed by > links to sample work-flows and a full dive into the plumbing (because at > this point the person should know enough to get by, now they need > reference material and examples more then a tutorial). Nope. A primer (i.e. a document to be read before the "real" teaching starts) should not cover more than the simplest/simplified model (see above). Of course, the courses should reference manual pages and more in-depth documentation wherever it makes sense, but we should make sure to note that such knowledge is not _required_ to follow the course. > ideally this would let people dive as deep as they are comfortable with, > or skim the explanation for the functionality > > I think one reason the 'plumbing first' approach gets a bad rap is that > it's so easy to get caught up into how clever you can get with the > plumbing. it's like teaching someone programming by spending a day > introducing them to concepts and language syntax, and then giving them > the entries in the obfuscated C contests as examples of how someone can > use them to get work done, but skipping any mention of libc or other > standard libraries. I see your point, but I still don't think teaching plumbing have any value in and of itself (unless you need to specifically learn plumbing to write porcelain code/scripts, in which case you'd better already know how to navigate the existing manual pages and other documentation). For newbies, I think plumbing should only be taught/mentioned when it simplifies or illustrates a concept in the bottom-up approach. > on the other hand, teaching only porcelain is like teaching them <insert > high-level *th generation buzzword language> without teaching any concept > of what they computer is doing under the covers, they can work, and even > get useful work done, but they will be limited on how effective they can > be. I don't agree that teaching only porcelain will not give them any concept of what their computer does "under the covers". I think we can teach porcelain with reference to the simplified object model, and still achieve a (simplified, but still rewarding) understanding of what happens at an object level. When I use Git myself, I normally only think in terms of the simplified model, and I have no problem getting things done without paying attention to the full object model (blobs, trees, etc) or the plumbing tools that are implicitly involved in the process. > you can't be a great programmer until you can understand both levels, the > under-the-covers 'plumbing' and the high level libraries of the > 'porcelain', trying to ignore either will limit you. Agreed. But we shouldn't need every Git user to be a great programmer. At least I hope not. Otherwise, there will be few Git users, indeed... ;) Many Git users will not be VCS geeks like us; they will be "regular" people that use Git because it's useful for them (or because they're forced to use Git at $dayjob). They will not be interested in how Git manages their data, and how a complex Git operation can be split into simple plumbing components. We should not require them to learn such details in order to become good Git users. Instead we should teach them Git using porcelain commands with reference to the simplified object model. They should learn how to use Git in a simple, yet still rewarding manner. ...and _that_ is how we achieve world domination ;) Have fun! :) ...Johan -- Johan Herland, <johan@xxxxxxxxxxx> www.herland.net -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
