On Mon, Nov 20, 2006 at 06:51:36PM -0500, linux@horizon.com wrote:
quoted text
> 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:

quoted text
> 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:

quoted text
> 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:

quoted text
> 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@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html