From: Petr Baudis <pasky@suse•cz>
To: Scott Chacon <schacon@gmail•com>
Cc: git list <git@vger•kernel.org>
Subject: Re: Git Community Book
Date: Tue, 29 Jul 2008 19:09:55 +0200 [thread overview]
Message-ID: <20080729170955.GK32184@machine.or.cz> (raw)
In-Reply-To: <d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com>
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
next prev parent reply other threads:[~2008-07-29 17:11 UTC|newest]
Thread overview: 50+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-07-29 16:20 Git Community Book Scott Chacon
2008-07-29 16:28 ` Miklos Vajna
2008-07-29 17:09 ` Petr Baudis [this message]
2008-07-29 18:30 ` Scott Chacon
2008-07-29 18:42 ` Junio C Hamano
2008-07-29 19:00 ` Julian Phillips
2008-07-29 19:09 ` Junio C Hamano
2008-07-30 13:27 ` markdown 2 man, was " Johannes Schindelin
2008-07-30 19:32 ` Junio C Hamano
2008-07-30 23:48 ` Wincent Colaiuta
2008-07-31 0:13 ` Scott Chacon
2008-07-31 0:30 ` Junio C Hamano
2008-07-31 11:24 ` Abdelrazak Younes
2008-07-31 13:01 ` Stephan Beyer
2008-07-31 14:13 ` Abdelrazak Younes
2008-07-31 14:33 ` Abdelrazak Younes
2008-07-31 15:09 ` Miklos Vajna
2008-07-31 15:29 ` Abdelrazak Younes
2008-07-31 19:00 ` Miklos Vajna
2008-08-01 0:45 ` Junio C Hamano
2008-08-01 7:11 ` Abdelrazak Younes
2008-08-01 9:46 ` Thomas Rast
2008-08-01 10:19 ` Abdelrazak Younes
2008-07-31 20:57 ` Jan Krüger
2008-08-01 7:50 ` Abdelrazak Younes
2008-08-01 10:45 ` Dmitry Potapov
2008-08-01 11:06 ` Abdelrazak Younes
2008-07-29 19:34 ` Scott Chacon
2008-07-29 19:57 ` Junio C Hamano
2008-07-30 21:39 ` J. Bruce Fields
2008-07-29 17:43 ` Junio C Hamano
2008-07-29 18:25 ` Junio C Hamano
2008-07-29 19:29 ` Scott Chacon
2008-07-29 19:24 ` Scott Chacon
2008-07-29 22:34 ` Daniel Barkalow
2008-07-29 22:47 ` Junio C Hamano
2008-07-30 13:20 ` Bart Trojanowski
2008-07-30 18:27 ` Junio C Hamano
2008-07-30 13:31 ` Bart Trojanowski
-- strict thread matches above, loose matches on Subject: below --
2008-09-05 19:08 Scott Chacon
2008-09-05 19:15 ` Thomas Adam
2008-09-05 20:45 ` Scott Chacon
2008-09-05 19:41 ` Junio C Hamano
2008-09-05 21:34 ` Scott Chacon
2008-09-05 22:09 ` Felipe Contreras
2008-09-06 6:33 ` Shawn O. Pearce
2008-09-06 18:14 ` Scott Chacon
2008-09-05 20:27 ` Linus Torvalds
2008-09-06 0:48 ` Stephan Beyer
2008-09-06 18:26 ` Christos Τrochalakis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20080729170955.GK32184@machine.or.cz \
--to=pasky@suse$(echo .)cz \
--cc=git@vger$(echo .)kernel.org \
--cc=schacon@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox