Re: improving the CG

[Trevor Daniels]

Graham Percival wrote Saturday, December 19, 2009 9:37 PM


> On Sat, Dec 19, 2009 at 02:16:19PM +0000, Ian Hulin wrote:
> > Trevor did a brilliant job with the Windows section and in some 
> > respects
> > it's clearer and less forbidding than the material in 1.1 to 1.4. 
> > It
> > also duplicates a lot of the material in those sections.

Thanks Ian - appreciation is very uplifting :)

> With respect, I disagree.  Trevor explains things.

Well, yes, I try to, because that is what _I_ want
to see when I am learning something new.  If you
don't understand how a tool works you end up using
it inefficiently at best and incorrectly at worst.

However in this case you're wrong.  Only the very
first section of CG 1.5 is anything like an explanation.
It just introduces the key git terms, most of which are
used later.  If I had seen a paragraph like this when
I was struggling to understand git two years ago I
would have been spared several frustrating weeks of
trial and error.  That's why I wrote it. The remainder
of CG 1.5 is just a set of concise recipes for doing the
essential things with git under Windows.  Read on and
see.

> Most
> contributors don't want to learn git; they just want to improve
> lilypond.  You don't need to understand git to improve lilypond --
> just look at what *I* manage to do without understand git.  The
> first thing I see in 1.5.1 is a wall of text talking about SHA-1
> and stuff.  My eyes glaze over and I immediately start to skim,
> because clearly the text isn't important.
>
> I just want to copy&paste, go get a coffee, then start editing
> files.

You might, but I don't agree this is a good attitude
to encourage in contributors who might go on to
write LilyPond code.  We need contributors whose
eyes do not glaze over when confronted with complexity.
Your advocated hit and often miss approach would result
in disaster if adopted by a programmer.

Trevor