Re: improving the CG

[Trevor Daniels]

Graham Percival wrote Saturday, December 26, 2009 5:18 PM
> I like this idea, but I'm not certain if we all have the same
> idea.  Here's the idea that I like:
>
> 1. introduction
>
> 1.1 help us: duplicate material from website
>
> 1.2 summary for unix developers: 2-3 paragraphs.  We use git, the
> docs are in git and generated with texinfo, we use google issue
> tracker, more details later in this manual, full stop.
>
> 1.3 summary for other contributors: 1-1.5 pages; the introduction
> that Mark has already written.

I'd be happy with this

> Speaking of focus, I'm getting a bit concerned about feature
> creep.  My initial reaction is that anything that would be
> appropriate to have in a separate appendix about git could be
> replaced with "To learn more about XYZ, see the git documentation
> or one of the many git tutorials".

In general I'd agree with you, but I remember the
difficulty I had with understanding the git concepts
initially.  The individual command manuals are
useless for this, and I failed to find a tutorial
that helped much (and in general I don't find it
difficult to pick up new stuff).  A page or so
to clearly explain the concepts and the simple
forms of the essential commands seems well worth
while to get enthusiastic potential contributors
moving up.

> The lilycontrib script has released a *huge* amount of pressure on
> the git stuff in the CG.  The biggest hurdle that new contributors
> faced was git; now that people (especially non-technical doc
> writers and translators) can do all their gitting with literally
> three clicks, I think it's time to look at who's left: technical
> people who want to do fancier stuff.

Plus the people who want to move on to the fancier
stuff, but lack the background knowledge.

[snip]

> As far as I know, all the lilypond developers apart from me have
> read various git documentation or tutorials, and they seem to be
> doing just fine with it.

But the CG isn't aimed at the existing lilypond
developers, it's to try to avoid _potential_ developers
dropping out early because they're frustrated.  OK, a
few of us have made it to the other side, but it
wasn't easy.  In my case it needed a lot of persistence
and an awful lot of screen-gazing time.  It still does,
although the barrier now is LilyPond's internal workings.
The easier this path is the greater will be the number of
potential developers who stay the course, and the quicker
they'll become effective.

Let's give them all the help we can.

Trevor