Announcement of Git wikibook

Announcement of Git wikibook

[Evan Carroll]

I've create a git wikibook if anyone wants to help expand it.
http://en.wikibooks.org/wiki/Source_Control_Management_With_Git

-- 
Evan Carroll
System Lord of the Internets
me@evancarroll.com
832-445-8877

Re: Announcement of Git wikibook

[Steffen Prohaska]

On Oct 19, 2007, at 10:21 PM, Evan Carroll wrote:

> I've create a git wikibook if anyone wants to help expand it.
> http://en.wikibooks.org/wiki/Source_Control_Management_With_Git

I'm just curious. What is the advantage of a wikibook?

We already have a manual

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

including a todo list

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#todo

So, why don't you send patches improving the manual, but instead
started a wiki book from scratch?

	Steffen

Re: Announcement of Git wikibook

[Ciprian Dorin Craciun]

    There is nothing wrong with either of the two approaches. They
could both coexist but address different needs:
    -- the manual should be more oriented on technical issues and
addresses only the most recent versions;
    -- the book should be more user-oriented, and more general,
explaining how source management should be addressed by using git, and
maybe make comparisons with may other versioning systems. Also the
book could relate to many versions -- both old and new.

    Also I would note that the wiki book is more easy to edit... If
you spot errors or want to add something you just go and edit it and
the effect is immediate. But in contrast sending patches involves some
overhead...

    Ciprian.


On 10/19/07, Steffen Prohaska <prohaska@zib.de> wrote:
>
> On Oct 19, 2007, at 10:21 PM, Evan Carroll wrote:
>
> > I've create a git wikibook if anyone wants to help expand it.
> > http://en.wikibooks.org/wiki/Source_Control_Management_With_Git
>
> I'm just curious. What is the advantage of a wikibook?
>
> We already have a manual
>
> http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
>
> including a todo list
>
> http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#todo
>
> So, why don't you send patches improving the manual, but instead
> started a wiki book from scratch?
>
>         Steffen

Re: Announcement of Git wikibook

[Wincent Colaiuta]

El 20/10/2007, a las 9:40, Ciprian Dorin Craciun escribió:

>     There is nothing wrong with either of the two approaches. They
> could both coexist but address different needs:
>     -- the manual should be more oriented on technical issues and
> addresses only the most recent versions;
>     -- the book should be more user-oriented, and more general,
> explaining how source management should be addressed by using git, and
> maybe make comparisons with may other versioning systems. Also the
> book could relate to many versions -- both old and new.
>
>     Also I would note that the wiki book is more easy to edit... If
> you spot errors or want to add something you just go and edit it and
> the effect is immediate. But in contrast sending patches involves some
> overhead...

But Git already has its own easy-to-edit, official wiki:

   http://git.or.cz/gitwiki

Creating a separate wiki book seems like an unnecessary duplication  
of effort.

(Obviously, you or anybody else is free to contribute documentation  
wherever you want.)

Cheers,
Wincent

Re: Announcement of Git wikibook

[Johannes Schindelin]

Hi,

[please do not top post]

On Sat, 20 Oct 2007, Ciprian Dorin Craciun wrote:

>     There is nothing wrong with either of the two approaches. They
> could both coexist but address different needs:
>     -- the manual should be more oriented on technical issues and
> addresses only the most recent versions;

The problem: it is not just "the manual".  It is the "user manual".

>     -- the book should be more user-oriented, and more general,
> explaining how source management should be addressed by using git, and
> maybe make comparisons with may other versioning systems. Also the
> book could relate to many versions -- both old and new.
> 
>     Also I would note that the wiki book is more easy to edit... If
> you spot errors or want to add something you just go and edit it and
> the effect is immediate. But in contrast sending patches involves some
> overhead...

I am torn.  On one side I like the Wiki approach.  On the other hand, the 
Wiki will get less review by git oldtimers, whereas the patches to 
user-manual are usually reviewed as thoroughly as the code patches.

Ciao,
Dscho

Re: Announcement of Git wikibook

[Steven Walter]

[-- Attachment #1: Type: text/plain, Size: 1577 bytes --]

On Sat, Oct 20, 2007 at 10:34:34PM +0100, Johannes Schindelin wrote:
> I am torn.  On one side I like the Wiki approach.  On the other hand, the 
> Wiki will get less review by git oldtimers, whereas the patches to 
> user-manual are usually reviewed as thoroughly as the code patches.

No offense, but review by old timers can be both a blessing and a curse.
Well, it's not the "review" that is so much a problem as the "editorial
control."  In my opinion (and I believe this is what the original poster
was saying), the official Git User Manual focuses more on technical
issues and less on introducing git to a new user.

This makes perfect sense given that it's edited by oldtimers, who are
neither inclined nor particularly suited to explaining git to newbies;
they have simply forgotten what it was like for these concepts to be
foreign.  They eat SHA1 hashes for breakfast and dream about index
files.  And that's great :)

I don't think the wikibook should try to duplicate the Git User Manual.
That would be a wasted effort.  But there is a niche to be filled in git
documentation, particularly in regard to specific workflows and git best
practices.  With git, TMTOWTDI.  It's quite difficult for a newbie to
know which of those ways will come back and bite them in the ass down the
road.

Of course, it is a wikibook, so it will go where it goes.  I for one am
glad to see this project started.
-- 
-Steven Walter <stevenrwalter@gmail.com>
Freedom is the freedom to say that 2 + 2 = 4
B2F1 0ECC E605 7321 E818  7A65 FC81 9777 DC28 9E8F 

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: Announcement of Git wikibook

[Wincent Colaiuta]

El 21/10/2007, a las 5:09, Steven Walter escribió:

> On Sat, Oct 20, 2007 at 10:34:34PM +0100, Johannes Schindelin wrote:
>> I am torn.  On one side I like the Wiki approach.  On the other  
>> hand, the
>> Wiki will get less review by git oldtimers, whereas the patches to
>> user-manual are usually reviewed as thoroughly as the code patches.
>
> No offense, but review by old timers can be both a blessing and a  
> curse.
> Well, it's not the "review" that is so much a problem as the  
> "editorial
> control."  In my opinion (and I believe this is what the original  
> poster
> was saying), the official Git User Manual focuses more on technical
> issues and less on introducing git to a new user.

But it's not an "intro", it's a user manual. That means it's supposed  
to be a comprehensive, in-depth treatment of just about everything.  
The technical content is a good thing; it's supposed to be the  
document you turn to when you want to move beyond superficial use to  
genuine, in-depth understanding.

There are other documents with the goal of "introducing git to the  
new user", grouped together here:

<http://git.or.cz/course/index.html>

And also under the "Documentation" heading on the Git home page:

<http://git.or.cz/>

Those are probably the articles that should be worked on and  
augmented if you care about introducing things to a newbie.

Cheers,
Wincent

Re: Announcement of Git wikibook

[Steffen Prohaska]

On Oct 21, 2007, at 11:10 AM, Wincent Colaiuta wrote:

> El 21/10/2007, a las 5:09, Steven Walter escribió:
>
>> On Sat, Oct 20, 2007 at 10:34:34PM +0100, Johannes Schindelin wrote:
>>> I am torn.  On one side I like the Wiki approach.  On the other  
>>> hand, the
>>> Wiki will get less review by git oldtimers, whereas the patches to
>>> user-manual are usually reviewed as thoroughly as the code patches.
>>
>> No offense, but review by old timers can be both a blessing and a  
>> curse.
>> Well, it's not the "review" that is so much a problem as the  
>> "editorial
>> control."  In my opinion (and I believe this is what the original  
>> poster
>> was saying), the official Git User Manual focuses more on technical
>> issues and less on introducing git to a new user.
>
> But it's not an "intro", it's a user manual. That means it's  
> supposed to be a comprehensive, in-depth treatment of just about  
> everything. The technical content is a good thing; it's supposed to  
> be the document you turn to when you want to move beyond  
> superficial use to genuine, in-depth understanding.

But it could also have introductory parts and parts decribing
specific workflows.

Something similar to svnbook or cvsbook would be perfect. I
believe a reasonable goal is that you'll get all need if you
search gitbook with google.

	Steffen