Re: Git in a Nutshell guide

[Jan Hudec <bulb@ucw.cz>]

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

On Wed, Nov 21, 2007 at 00:57:28 +0100, Jakub Narebski wrote:
> 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>

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