Re: Git Community Book

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