Bug 316529

Description Matthias Sohn 2010-06-10 16:24:47 EDT

Copied from bug 315291 to track this request separately:

Kay Huber 2010-06-03 02:33:57 EDT wrote:

Don't get me wrong, the documentation is truly impressive and (far) better than
many documentations for eclipse plugins - I especially like the many
screenshots since they make it much simpler to understand the dialogs.
What I notice about the documentation in general, is that it perfectly well
describes the egit functionality but it assumes, that the git concepts are
already clear to the end user.

Example: 
{quote}
"Pulling New Changes from Upstream":
This is not yet fully available.
In cases where fast-forward merges are sufficient (full merge is not yet
implemented) you may run pull in EGit the following way.
{quote}

This description assumes:
* The user knows the difference between "fetching" (previous chapter) and
"pulling" changes
* Coming from git, the user probably knows what pull is. Thus, it's written,
pull "as in git" is not yet fully available. Users not common to git just don't
know what that means.
* "fast-forward merge" - this is definitely git terminology. I could imagine
that even many git users don't know the difference between doing fast-forward
and full merge, they just merge, and it usually works just fine.

Another example : As a former SVN user, the "Commit" term means: Put that
change into the central repo such that everybody else can grab it there. In
(e)git, committing has a completely different meaning.

Again: This is not critical. I'd even leave it all as is, but what I would
suggest is to add a chapter for all those that have been using eclipse in the
past with the so-far-available team scm providers (CVS/SVN/etc.). These team
providers have been so completely different in their base concepts, that many
users may need some "transition explanation".

I'd give at least some introductory links to e.g.
* http://git-scm.com/ (maybe even "copy" the introduction "Git is..." from that
page)
* http://git-scm.com/documentation (Especially the "Short and Sweet" section is
a good start)
* http://git-scm.com/course/svn.html *very* important IMHO. You may even
consider doing something similar directly in your documentation (comparison:
"this is how it was done in SVN, this is how to do in egit").
* https://git.wiki.kernel.org/index.php/GitFaq (many answers to users not sure
what to expect from git)
* Maybe add a egit FAQ with something like "how it differs from git" for git
users
* Maybe add a "terminology" section, where "fetch", "commit", "pull", "push",
et al are described and maybe also put in relation to already known "similar"
terms from other team providers.

Anyway, sorry, this comment is now definitely "off-topic" - If you prefer, I'll
add it again to a new bug for further discussion :-)