On Mon, Nov 20, 2006 at 06:51:36PM -0500, linux@xxxxxxxxxxx wrote: > I tried to incorporate all the suggestions. There are still a few things > I have to research, and now I'm worried it's getting too long. Sigh. If you made another pass for it asking whether each sentence was really absolutely necessary you'd be able to cut quite a bit without compromising on content. One example: > In CVS, branches are difficult and awkward to use, and generally > considered an advanced technique. Many people use CVS for a long time > without departing from the trunk. Lots of people have CVS experience, but not everyone does, and this paragraph isn't really necessary. Cut it out, and the following paragraph (minus first sentence) stands just fine on its own: > Git is very different. Branching and merging are central to effective use > of git, and if you aren't comfortable with them, you won't be comfortable > with git. In particular, they are required to share work with other > people. Note also "if you aren't comfortable with them..." just repeats something you've already said. So now we're down to just: "Branching and merging are central to effective use of git. In particular, they are required to share work with other people." which is short and to the point. Neat! I'm not sure of the ordering. For example: > The only things that are a bit confusing are some of the names. > In particular, at least when beginning: > - You create new branches with "git checkout -b". > "git branch" should only be used to list and delete branches. > - You share work with "git fetch" and "git push". These are opposites. > - You merge with "git pull", not "git merge". "git pull" can also do a > "git fetch", but that's optional. What's not optional is the merge. > > Also, a good habit it to never commit directly to your main "master" > branch. Do all work in temporary "topic" branches, and then merge them > into the master. Most experienced users don't bother to be quite this > purist, but you should err on the side of using separate topic branches, > so it's excellent practice. We're diving in here without explaining what checkout, fetch, push, pull, or merge are yet, or what the master branch is. The document seems to be targetted at someone who has read some scattered git documentation, gotten confused, and needs help putting it all together. This is understandable--there are a lot of people like that right now! But if we're going to get the documentation in some sort of sensible order then we need to think about how to start with someone who is a blank slate and lead them step by step to what they most need to know. That doesn't mean *you* need to do everything from scratch, but it would be helpful to figure out where this would fit in with the other documentation in a logical progression. As a start, the first paragraph could say "before reading this, we assume you've read X, Y, and Z", and then the rest of the document could be audited to make sure that it didn't assume anything that isn't in X, Y, and Z. --b. - 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