git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: Git Community Book

From
Petr Baudis <pasky@suse.cz>
Date
Jul 29, 2008, 17:09 UTC
Message-ID
<20080729170955.GK32184@machine.or.cz>
In-Reply-To
<d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com>
On Tue, Jul 29, 2008 at 09:20:20AM -0700, Scott Chacon wrote:
Show 11 quoted lines
> 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.

Show 7 quoted lines
> 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? ;-)

Show 5 quoted lines
> 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
Previous: Miklos VajnaNext: Scott Chacon
Message 3 of 39 in “Git Community Book”
  1. Scott ChaconJul 29, 2008
  2. Miklos VajnaJul 29, 2008
  3. Petr BaudisJul 29, 2008
  4. Scott ChaconJul 29, 2008
  5. Junio C HamanoJul 29, 2008
  6. Julian PhillipsJul 29, 2008
  7. Junio C HamanoJul 29, 2008
  8. markdown 2 man, was Re: Git Community BookJohannes Schindelin, Jul 30, 2008
  9. Junio C HamanoJul 30, 2008
  10. Wincent ColaiutaJul 30, 2008
  11. Scott ChaconJul 31, 2008
  12. Junio C HamanoJul 31, 2008
  13. Abdelrazak YounesJul 31, 2008
  14. Stephan BeyerJul 31, 2008
  15. Abdelrazak YounesJul 31, 2008
  16. Abdelrazak YounesJul 31, 2008
  17. Miklos VajnaJul 31, 2008
  18. Abdelrazak YounesJul 31, 2008
  19. Miklos VajnaJul 31, 2008
  20. Junio C HamanoAug 1, 2008
  21. Abdelrazak YounesAug 1, 2008
  22. Thomas RastAug 1, 2008
  23. Abdelrazak YounesAug 1, 2008
  24. Jan KrügerJul 31, 2008
  25. Abdelrazak YounesAug 1, 2008
  26. Dmitry PotapovAug 1, 2008
  27. Abdelrazak YounesAug 1, 2008
  28. Scott ChaconJul 29, 2008
  29. Junio C HamanoJul 29, 2008
  30. J. Bruce FieldsJul 30, 2008
  31. Junio C HamanoJul 29, 2008
  32. Junio C HamanoJul 29, 2008
  33. Scott ChaconJul 29, 2008
  34. Scott ChaconJul 29, 2008
  35. Daniel BarkalowJul 29, 2008
  36. Junio C HamanoJul 29, 2008
  37. Bart TrojanowskiJul 30, 2008
  38. Junio C HamanoJul 30, 2008
  39. Bart TrojanowskiJul 30, 2008

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.