Git Community Book

So I wanted to develop a really nice, easy to follow book for Git
newcomers to learn git quickly and easily.  One of the issues I
remember having when learning Git is that there is a lot of great
material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -
but they're all huge long documents that are sometimes difficult to
come back to and remember where you were, and I didn't know which one
to start with or where to find what I was looking for, etc.

So, what I've started to do is pull material from all of them into a
single book which will be available in online HTML (one page per
chapter) and downloadable PDF form.  I'm trying to give it a very
organized flow that will hopefully be a bit easier to follow and
digest than the current formats, and including a number of diagrams,
illustrations and screencasts to supplement the text.  Where possible,
I am also trying to simplify the explanations a bit to be a tad more
digestible for beginning users, at least in the first couple dozen
chapters. I have put the current html output of this book here:

http://book.git-scm.com

It is not complete - the grey links are chapters that are very short
or completely empty - but it is a start.  Please let me know what you
think, and if anyone is interested in helping with the project, give
me a shout.

Also, for credit, I have generated an Authors page I will be linking
to the site soon that lists everyone that contributed a patch to any
of the Git User Guide, Git Tutorials, etc.  It is in the PDF right
now, but not in the HTML version yet (and the PDF is not yet linked to
the site).

Thanks,
Scott

On Tue, Jul 29, 2008 at 09:20:20AM -0700, Scott Chacon [off-list ref] wrote:

It is not complete - the grey links are chapters that are very short
or completely empty - but it is a start.  Please let me know what you
think, and if anyone is interested in helping with the project, give
me a shout.

At http://github.com/schacon/learn-github/wikis/how-to-contribute, there
is a typo: you want 'git checkout origin/book'. ;-)

On Tue, Jul 29, 2008 at 09:20:20AM -0700, Scott Chacon wrote:

So, what I've started to do is pull material from all of them into a
single book which will be available in online HTML (one page per
chapter) and downloadable PDF form.  I'm trying to give it a very
organized flow that will hopefully be a bit easier to follow and
digest than the current formats, and including a number of diagrams,
illustrations and screencasts to supplement the text.  Where possible,
I am also trying to simplify the explanations a bit to be a tad more
digestible for beginning users, at least in the first couple dozen
chapters. I have put the current html output of this book here:

http://book.git-scm.com

I think what most of the people here would be also interested in is

	http://github.com/schacon/learn-github/wikis/how-to-contribute

There is no license in the source code - what are the copying terms?

It is maybe somewhat unfortunate that this is in a different format that
the standard git choice asciidoc, but the formats do look rather similar
so I assume it should not be hard to even convert from one to another if
needed.

Unfortunately, I probably won't have enough time to review the content
in details anytime soon, so I can only say that that the site looks
pretty. :-) I have skimmed through the Introduction part only, but
frankly, my feelings are somewhat mixed; I think the "direct dive-in"
you take in the Database and Index section is controversial at best, and
I personally much prefer the gentle approach of user manual, which does
not hurl details on git's objects model on the user right away. To me,
it would make sense to move this all somewhere between chapter four and
five. (Incidentally, only after writing this, I have looked at the
actual structure of the User Manual and I think it makes more sense than
your approach.)

So my confusion still is - where does this stand wrt. the user manual?
Why didn't you just start with the manual and work on that? I thought
you were planning to do that, but apparently we misunderstood each other
in the last mails.

Which goals are different between the Git Community Book and the User
Manual? It seems to me that the intent is the same in both cases, and if
the User Manual is not sufficiently digestible and easy to understand
for a newcomer, wouldn't it make more sense to make it so?

The thought of yet another Git resource _in addition_ to the existing
ones just makes me nervous. This isn't only about your time that I feel
is being spent unnecessarily ineffectively by not building upon the
existing text, but also about the _community_ resources - the user
manual has a great benefit that it was actually reviewed by the mailing
list so it will probably have quite smaller error rate than anything
you or me would write on our own, no matter how big Git expert you are.

I'm not saying you don't have good reasons to make the choice you did,
I just don't understand them yet - please help me here.

So I wanted to develop a really nice, easy to follow book for Git
newcomers to learn git quickly and easily.  One of the issues I
remember having when learning Git is that there is a lot of great
material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -
but they're all huge long documents that are sometimes difficult to
come back to and remember where you were, and I didn't know which one
to start with or where to find what I was looking for, etc.

So, one of your arguments is that the current material are huge long
documents that are difficult to come back to and remember where you
were. But if I'd split the User Manaul TOC to the same layout you use
for the Community Book, what is the difference here? It seems to me that
both would appear pretty much the same. Should I do a proof of concept?
;-)

Also, for credit, I have generated an Authors page I will be linking
to the site soon that lists everyone that contributed a patch to any
of the Git User Guide, Git Tutorials, etc.  It is in the PDF right
now, but not in the HTML version yet (and the PDF is not yet linked to
the site).

So, right now you are basically taking existing material and rearranging
it? By what rules? What is the underlying idea of your approach, and why
is it better than the current structure of the user manual? Have you
considered how to perform this all so that you can easily get further
updates and corrections to the user manual?

-- 
				Petr "Pasky" Baudis
As in certain cults it is possible to kill a process if you know
its true name.  -- Ken Thompson and Dennis M. Ritchie

"Scott Chacon" [off-list ref] writes:

So I wanted to develop a really nice, easy to follow book for Git
newcomers to learn git quickly and easily.  One of the issues I
remember having when learning Git is that there is a lot of great
material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -
but they're all huge long documents that are sometimes difficult to
come back to and remember where you were, and I didn't know which one
to start with or where to find what I was looking for, etc.

Interesting.  A few comments, before I get dragged into my day job fully.

[overall]

 - Some people mentioned that the necessity of reading through large
   volume of documentation can be reduced if they were divided by
   developer roles (similar to how Everyday does), e.g. people in
   individual contributor role does not have to learn integrator tools
   such as "am" in their first pass on the documentation.  Has the
   approach considered while developing this book?

 - The order of sections in "Working with Git" chapter somehow does not
   feel quite right, except that I'd agree that "Git on Windows" at the
   beginning is a very good idea (disclaimer. I do not use Windows
   myself). "StGIT" coming next was very understandable, but then
   "Capistrano"????  And no CVS section next to Subversion section?  Ruby
   before Perl or Python (I would have listed Perl, Python and then Ruby
   to avoid language wars.  That's the language age order, and it is even
   alphabetical)???

   Above "Capistrano" and "Ruby" comment shows the bias this TOC has (and
   my bias being different from the TOC's bias).  I'd imagine that
   Ruby-minded folks won't share the same reaction as I had.  What's the
   target audience of this book?  Git users in general, or primarily
   Ruby-minded subset?  If the latter, labeling this as "Community Book"
   may be misleading.

[http://book.git-scm.com/1_the_git_object_database.html]

 - The color of "blob" does not match the blob that is committed to eat
   trees at the top of your site ;-)

 - In a recent thread on the list, quite a lot of people seem to have
   found that teaching the low level details and plumbing first to the new
   people is detrimental.  Do you have response to that thread?

There is no license in the source code - what are the copying terms?

I copied in the COPYING file from Git - GPL2.

It is maybe somewhat unfortunate that this is in a different format that
the standard git choice asciidoc, but the formats do look rather similar
so I assume it should not be hard to even convert from one to another if
needed.

I simply didn't want to get asciidoc working locally - it's always
been a bit of a pain to compile (I've heard it referred to more than
once as the only 'nightmare dependancy' in git), and I don't need to
make man pages or anything, so it seemed Markdown would be a better
choice for my output targets.  There are a number of good Markdown
interpreters and they're easy to get running.

Unfortunately, I probably won't have enough time to review the content
in details anytime soon, so I can only say that that the site looks
pretty. :-) I have skimmed through the Introduction part only, but
frankly, my feelings are somewhat mixed; I think the "direct dive-in"
you take in the Database and Index section is controversial at best, and
I personally much prefer the gentle approach of user manual, which does
not hurl details on git's objects model on the user right away. To me,
it would make sense to move this all somewhere between chapter four and
five. (Incidentally, only after writing this, I have looked at the
actual structure of the User Manual and I think it makes more sense than
your approach.)

So my confusion still is - where does this stand wrt. the user manual?
Why didn't you just start with the manual and work on that? I thought
you were planning to do that, but apparently we misunderstood each other
in the last mails.

I was originally planning on doing that, but the problem is the
graphics, diagrams and screencasts.  Unless I am mistaken, there is
not a single outside media reference in any of these guides - the
diagrams that are there are all ascii drawings.  I'm assuming there is
a reason for that. If I wanted to add images and screencast embeds
into the guide, how would that work?

Also, the user guide seems much more technical than I wanted - I
wanted to simplify a lot of the explanations, especially at the
beginning, and I don't want to screw up all the existing text.  I
thought that the best solution would be to have the Community Book as
more of a book format, and the User Guide as more of an advanced
technical guide.  We don't want to put 'Git and Capistrano' or 'Using
Git in Perl' in the User Guide, do we?  I just wanted to copy the
sections that were already well written that need to be in both, so
that I don't have to re-write them.

Which goals are different between the Git Community Book and the User
Manual? It seems to me that the intent is the same in both cases, and if
the User Manual is not sufficiently digestible and easy to understand
for a newcomer, wouldn't it make more sense to make it so?

I think the goals are a bit different.  I think the User Manual is
helpful for people coming from the Linux/Perl hacker communities that
are more used to guides like that - who like things explained more
technically and possibly even think screencasts are stupid and an
ascii graph is just as understandable as a pretty one with rounded
corners and pastel colors.

I think my goal with the book is to create a book.  The length of a
book, readable one chapter at a time over several days, etc.  Also,
eventually, I want to make it bookmarkable, maybe add some interactive
quizzes at the end of each chapter, maybe add a comments section to
the end of each chapter, add a live search box, etc.  That just seems
so much different than the User Guide and Tutorials that it warrants a
different project, but so much of the content in the Guide is quality
that I didn't want to reinvent the wheel yet again.

The thought of yet another Git resource _in addition_ to the existing
ones just makes me nervous. This isn't only about your time that I feel
is being spent unnecessarily ineffectively by not building upon the
existing text, but also about the _community_ resources - the user
manual has a great benefit that it was actually reviewed by the mailing
list so it will probably have quite smaller error rate than anything
you or me would write on our own, no matter how big Git expert you are.

Well, that's what the point of this is - to ask everyone to help me
review it, and possibly help me add to it.  The user manual is great,
but even I don't reference it very often because I find it difficult
to find content in it I need quickly.  As Git becomes more and more
popular, more and more resources will continue to come out - I did the
Peepcode mini-book, which sold over a thousand copies already, and
Pragmatic Programmers and O'Reilly both have Git books in the works,
too.  I was planning on a second book with Peepcode, but I thought it
would be better to do this instead.

I would love to develop a book that is totally open and rivals all of
those and is consistently up to date and allows the community to
interact.  I don't think it's really possible to get the User Guide
there very easily except in this way.

So, one of your arguments is that the current material are huge long
documents that are difficult to come back to and remember where you
were. But if I'd split the User Manaul TOC to the same layout you use
for the Community Book, what is the difference here? It seems to me that
both would appear pretty much the same. Should I do a proof of concept?
;-)

Again, I started to do this, but the image references, screencast
embeds, and general different goal of the book, both in length and
scope, makes me think that is not the best way to go.

So, right now you are basically taking existing material and rearranging
it? By what rules? What is the underlying idea of your approach, and why
is it better than the current structure of the user manual? Have you
considered how to perform this all so that you can easily get further
updates and corrections to the user manual?

I have thought about this a lot, and it comes from the talks and
training I've done with Git and the feedback I've gotten from that.
For one, I think it's very helpful to split up the chapters into
sections ('First Time', 'Basic Usage', 'Advanced Usage', etc) so users
of different skill levels can easily see which chapters may have
something for them at a glance.

The specific order I choose is very different from the User Guide and
is likely to bother a number of people, which you mentioned (and I'm
sure Dscho will _hate_) because I introduce the object model at the
beginning.  (I'm still working on that section, trying to simplify it
and add in some other diagrams and a short screencast I have that I
think will be helpful)  This is because I have had a lot of positive
feedback that primary frustration from people comes from them thinking
of Git as a super-better Subversion.  I would venture to say that
_most_ of the users coming to Git now are currently fluent in
Subversion.  Even if they are from Perforce or CVS (the other two ones
I will occasionally run into), their mental model of what an SCM does
is the same - delta storage.  I've found that by ridding them of that
notion off the bat, they have _far_ fewer problems and frustrations
with Git than when I just try to show them the first 10 commands in
sort of a cookbook style.  It's not a complicated model, it doesn't
take long to teach, and in _my personal_ experience (which is not to
say it's necessarily correct), it helps people the most in picking it
up and really loving the tool.

The book is built so that it is just as easy to start in the 'Basic
Usage' section and go back later, but if you're going to sit down and
just start reading, I think it would be better to explain why Git is
different at a fundamental level right off the bat.

Scott

On Tue, Jul 29, 2008 at 10:43 AM, Junio C Hamano [off-list ref] wrote:

"Scott Chacon" [off-list ref] writes:

quoted

So I wanted to develop a really nice, easy to follow book for Git
newcomers to learn git quickly and easily.  One of the issues I
remember having when learning Git is that there is a lot of great
material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -
but they're all huge long documents that are sometimes difficult to
come back to and remember where you were, and I didn't know which one
to start with or where to find what I was looking for, etc.

Interesting.  A few comments, before I get dragged into my day job fully.

[overall]

 - Some people mentioned that the necessity of reading through large
  volume of documentation can be reduced if they were divided by
  developer roles (similar to how Everyday does), e.g. people in
  individual contributor role does not have to learn integrator tools
  such as "am" in their first pass on the documentation.  Has the
  approach considered while developing this book?

Not really - I'm assuming that everyone will have to be one of those
roles at some point - I'm mostly aiming at the smaller developers like
myself, and probably 90% of the Git users, who have 20 git projects
that they work on with 1-5 other people.  I am not aiming at the Linux
or Git developers that have to deal with a project with hundreds of
users - everyone is going to have to be a developer, participant,
integrator and administrator to some degree, so I wanted to introduce
those commands when you need them.  IE, 'gc' and 'fsck' are rarely
_needed_ by most users - you can work just fine for a really long time
without ever needing to run them, but they are first in the Everyday
list.  I'm ordering it roughly in the order that I've seen people need
certain commands.  I could be convinced otherwise on any of them,
though.

 - The order of sections in "Working with Git" chapter somehow does not
  feel quite right, except that I'd agree that "Git on Windows" at the
  beginning is a very good idea (disclaimer. I do not use Windows
  myself). "StGIT" coming next was very understandable, but then
  "Capistrano"????  And no CVS section next to Subversion section?  Ruby
  before Perl or Python (I would have listed Perl, Python and then Ruby
  to avoid language wars.  That's the language age order, and it is even
  alphabetical)???

This is basically just notes at this point.  I will likely re-arrange
them as they are written.  However, I would argue that there are
likely more Git people using Ruby than there are using Python, though
Perl might rival it.  Nearly every major Ruby project out there is now
using Git, whereas very few Python ones seem to be (possibly because
Mercurial is written in python) - however, in all honesty, I don't
really care what order they are in.

As for the Capistrano section - again it is demand.  I have had tons
and tons of questions about Capistrano and Git, and many thousands of
people use that combination or are beginning to.  Again though, I
don't care where it is - I would be happy to put it at the bottom of
the section.

  Above "Capistrano" and "Ruby" comment shows the bias this TOC has (and
  my bias being different from the TOC's bias).  I'd imagine that
  Ruby-minded folks won't share the same reaction as I had.  What's the
  target audience of this book?  Git users in general, or primarily
  Ruby-minded subset?  If the latter, labeling this as "Community Book"
  may be misleading.

The target audience are users being convinced by their friends to use
Git and I want to impress them with a well thought out and laid out,
comprehensive, easy to use website and book as their first experience,
and show them an easy and smooth path to switch their mind from
thinking in SVN/Perforce to thinking in Git.  The Ruby community is a
very large part of the current surge to Git right now, but I want the
book to be easily accessible and acceptable to all communities that
are doing that.

[http://book.git-scm.com/1_the_git_object_database.html]

 - The color of "blob" does not match the blob that is committed to eat
  trees at the top of your site ;-)

 - In a recent thread on the list, quite a lot of people seem to have
  found that teaching the low level details and plumbing first to the new
  people is detrimental.  Do you have response to that thread?

I think I addressed this in a previous response.  As for the blob
color, a number of diagrams I am planning to introduce initially are
from a talk I gave at RailsConf on Git, and I will likely go back over
them a bit later.

Thanks,
Scott

On Tue, 29 Jul 2008, Scott Chacon wrote:

So I wanted to develop a really nice, easy to follow book for Git
newcomers to learn git quickly and easily.  One of the issues I
remember having when learning Git is that there is a lot of great
material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -
but they're all huge long documents that are sometimes difficult to
come back to and remember where you were, and I didn't know which one
to start with or where to find what I was looking for, etc.

It would be good to include stuff from 
http://eagain.net/articles/git-for-computer-scientists/

Maybe only in inspiration, since it doesn't have an obvious license and 
it's stylisticly more technical. But it would be nice to have diagrams of 
"this is what git thinks of as history", possibly even arranging them like 
gitk shows things (older downward, refs pointing in from the side).

In particular, I think it's really useful to show a commit graph with 
branching and merging, and introduce refs as movable pointers to commits 
in the graph, and local branches as refs that you move and tracking refs 
as refs that copy values in other repositories.

I think you can even gloss of details of blobs and trees because they 
pretty much work just like files and directories in a filesystem (except 
that they take up much less storage in large quantities than you'd think). 
The only potentially interesting things are (1) a blob names the inode, 
not the dentry, so it's the file contents, not the name, mode, etc; and 
(2) the permission bits are just 'x', we've got symlinks, there are no 
owner/group or other attributes and "see also Submodules".

But I think that the section:
  http://eagain.net/articles/git-for-computer-scientists/#history
should have an equivalent in any git documentation that can have diagrams, 
and introducing a history diagram style early means that you can do a 
bunch of simple pictures to explain operations like "git checkout -b foo" 
or "git reset --hard HEAD^^" or "git checkout origin/master".

	-Daniel
*This .sig left intentionally blank*

quoted

So my confusion still is - where does this stand wrt. the user manual?
Why didn't you just start with the manual and work on that? I thought
you were planning to do that, but apparently we misunderstood each other
in the last mails.

On Tue, Jul 29, 2008 at 11:30:55AM -0700, Scott Chacon wrote:

I was originally planning on doing that, but the problem is the
graphics, diagrams and screencasts.  Unless I am mistaken, there is
not a single outside media reference in any of these guides - the
diagrams that are there are all ascii drawings.  I'm assuming there is
a reason for that. If I wanted to add images and screencast embeds
into the guide, how would that work?

Yeah, some possible obstacles:

	- Size: People probably won't want large binary blobs added to
	  the git repository.
	- Editability: We want to be able to keep the materials up to
	  date and accurate.
	- Source readability: the current documentation can all be read
	  in place without doing a build.
	- Build requirements: I seem to recall complaints about the
	  toolchain required to build the existing documentation.

At least for simple diagrams it might be possible to solve most of those
problems with an appropriate diagram-description-language that could be
compiled into image files.  Screencasts are probably totally out,
though.

In cases where you do find you're working with the same material, any
improvements you could contribute back to the in-tree documentation
would of course be appreciated.

Well, that's what the point of this is - to ask everyone to help me
review it, and possibly help me add to it.  The user manual is great,
but even I don't reference it very often because I find it difficult
to find content in it I need quickly.

If you had notes on any particular examples (I looked for X in place Y,
then place Z, and finally found it where I least expected it in place
Q...), they'd be appreciated.

The specific order I choose is very different from the User Guide and
is likely to bother a number of people, which you mentioned (and I'm
sure Dscho will _hate_) because I introduce the object model at the
beginning.  (I'm still working on that section, trying to simplify it
and add in some other diagrams and a short screencast I have that I
think will be helpful)  This is because I have had a lot of positive
feedback that primary frustration from people comes from them thinking
of Git as a super-better Subversion.

I would venture to say that
_most_ of the users coming to Git now are currently fluent in
Subversion.  Even if they are from Perforce or CVS (the other two ones
I will occasionally run into), their mental model of what an SCM does
is the same - delta storage.  I've found that by ridding them of that
notion off the bat, they have _far_ fewer problems and frustrations
with Git than when I just try to show them the first 10 commands in
sort of a cookbook style.  It's not a complicated model, it doesn't
take long to teach, and in _my personal_ experience (which is not to
say it's necessarily correct), it helps people the most in picking it
up and really loving the tool.

I've considered doing the same for the user manual, actually, for some
of the same reasons--my main concern would be that it be done very
quickly, so as not to make people feel like it was a big obstacle on
their way to actually doing what they need to do.

So, anyway, that's to say that suggestions for reorganization of the
in-tree documentation (as opposed to just smaller-scale fixes) would
also be welcomed....

--b.

The book is built so that it is just as easy to start in the 'Basic
Usage' section and go back later, but if you're going to sit down and
just start reading, I think it would be better to explain why Git is
different at a fundamental level right off the bat.

Scott
--
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