Re: Git Books

From: Jakub Narebski <jnareb@gmail.com>
Date: Dec 6, 2008, 12:54 UTC
Message-ID: <m34p1hihx4.fsf@localhost.localdomain>
In-Reply-To: <d411cc4a0812060358ub640ea3kd04072c5640eef68@mail.gmail.com>

"Scott Chacon" <schacon@gmail.com> writes:

Show 13 quoted lines

> I have been talked into helping write a real, paper-based book on Git
> for a publisher big enough that you may even see it in your local
> Borders or whatnot.  (And, it appears that Junio has been as well:
> http://gitster.livejournal.com/21616.html)
> 
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.

What I really would like to see in a paper book is _diagrams_, in the form of simple graphs (and not UML-like diagrams, of flow-control like diagrams). You can find them in various slides for presentations (among others Junio's talks), and sometimes in blog posts[1], but usually only as ASCII-diagrams[2] in git documentation. (And the examples in"The Git Comminity Book" I've seen so far are a bit too complicated).

For example explaining git object model, explaining refs: local branches, remote-tracking branches and tags, explaining pulling and pushing, explaining merging and 3-way merge algorithm are difficult to do without diagrams; diagrams make it much easier to understand.

Others have emphasized workflows enough...

Footnotes:
==========
[1] http://www.gnome.org/~federico/news-2008-11.html#pushing-and-pulling-with-git-1
[2] This is understandable, as while AsciiDoc format makes it quite
    good on promise to be easy to edit for non-tech users, AFAIK there
    is no such format for diagrams and pictures.  PIC and Asymptote
    nonwithstanding.

-- 
Jakub Narebski
Poland
ShadeHawk on #git