Re: Git in a Nutshell guide

From: Jan Hudec <bulb@ucw.cz>
Date: Nov 21, 2007, 19:45 UTC
Message-ID: <20071121194507.GA3569@efreet.light.src>
In-Reply-To: <fhvs95$5qk$1@ger.gmane.org>

On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:

Show 8 quoted lines

> I think that writing proper "Git Guide" aka "The Git Book" is hard because
> of some things:
> 
>  1. Git has many useful advanced features. Describing those advanced
>     features is not easy. For example git uses multiple branches in single
>     repository paradigm freely, which makes learning curve a bit steeper;
>     IIRC hgbook describes one branch per repos situation (at least at
>     beginning), which is easier.

I think I saw the "sharp curve" and "double sharp curve" paragraphs in other places besides the the TeXbook. I even have an impression (without actually looking) that it was documentation of some version control system.

That deals with difficult to read, but it does make it more difficult to write.

>  2. Git has some historical cruft, including the fact that it began as
>     series of low level tools (plumbing) and became proper SCM (acquired
>     proper porcelain) later, what can be even now seen in documentation...

Most plumbing can be safely ignored through most of the book or covered by those "double sharp curve" paragraphs. It unfortunately does make it harder to write, because the author has to consider what to cover and what to hide.

>  3. Explanation of some features (like object model) would be much easier
>     with some graphics (diagrams etc.), but chosen documentation format,
>     AsciiDoc, doesn't make it easy...

I dare to disagree here. Asciidoc supports generating image tags for respective output formats and it really does not look hard. We could have PNGs and if we wanted higher press quality even SVG or EPS and convert them to PNGs for the HTML version (and use EPS for latex output).

-- 
						 Jan 'Bulb' Hudec <bulb@ucw.cz>