Re: Git Community Book

From: Scott Chacon <schacon@gmail.com>
Date: Jul 29, 2008, 19:24 UTC
Message-ID: <d411cc4a0807291224h65e4746cgda94ee66a4ab5da0@mail.gmail.com>
In-Reply-To: <7vmyk0fux8.fsf@gitster.siamese.dyndns.org>

On Tue, Jul 29, 2008 at 10:43 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 21 quoted lines

> "Scott Chacon" <schacon@gmail.com> 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?
>

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.

Show 9 quoted lines

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

Show 6 quoted lines

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

Show 9 quoted lines

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