Re: improving the CG

[Carl Sorensen]

On 12/27/09 6:45 PM, "John Mandereau" <address@hidden> wrote:

> Le dimanche 27 décembre 2009 à 18:20 -0700, Carl Sorensen a écrit :
>> And I don't see much of a maintenance headache; basic git isn't likely to
>> change much, and all we're using is basic git.
> 
> This hasn't been true in the past, remember the merge of
> git-update-index and git-add commands into git-add.  As for Git
> concepts, you're right that they don't change much, but see my next
> comment.
> 

I don't remember git-update-index merging with git-add, because that merge
happened before my time.  But suppose it did.  Somebody would try the
instructions that are wrong, and post on either -devel, -user, or frogs-
that the instructions in the CG didn't work, and then they'd get fixed.  And
it takes very little time to fix documentation like this.

<snip>

> 
>> I think that the most effective way to provide this help is with a small
>> customized tutorial (including all of the downstream maintenance).
> 
> Anyway, in case this kind of issue is relevant
> for new Git users that work with Lily sources, I'm sure that it would be
> equally well addressed in a generic Git documentation, but with the
> added benefit of a greater audience.

Oh, I agree that it would have the added benefit of a greater audience, but
it would also cost more time for Mark to get it into the Git documentation
instead of into the LilyPond documentation.

If Mark is interested in doing that, I'm totally fine with it.  I think that
would be a very useful thing to do.

But if he's not interested in doing it, and he judges that it would take
less of his time to just do something for LilyPond in the LilyPond
documentation, then I'm OK with that, too.

And if it really is a good intro that will be helpful to others, then I
believe that Google will eventually find it and it will provide help to a
wider-than-LilyPond audience.

As Mark pointed out earlier when he asked if he was a Frog, he's not
interested in being told what to work on.  He's interested in making a
contribution on things he thinks are valuable.  I think that our stance
should be that we accept things of value to LilyPond.  I am of the opinion
that a well-written tutorial on getting up to speed with Git for LilyPond
would be helpful (even if it's not necessary).

Who knows, maybe we'll find that lily-git.tcl will make it so easy to use
git that nobody will ever read the tutorial.  But until we get to that
point, whatever we can do to decrease the effort required to get patches
contributed will greatly help.

After all, I look at the CG (which is really not very well-edited, at least
the parts that I contributed), and I see that even with all its weaknesses,
it helps *me*, because there's a place to go to get my questions answered.
As far as I'm concerned, if a developer climbs the hurdles to be able to
contribute, then wants to reach back and help others with the climb, we
ought to encourage it.  Because the one who just made the climb has the best
vision of what the obstacles were, so their help is likely to be the most
relevant to a newcomer.

I can remember spending days trying to figure out how to work with Git.  I
read tutorial after tutorial, and man page after man page, and nothing
seemed to make sense.  Then, gradually, it started to make sense to me, and
now I'm quite comfortable with the set of commands I regularly use.  But
unfortunately, I can't remember now exactly what was so hard about it.  Once
I went through the paradigm shift, git became quite easy to use.  But I
remember that when I was first introduced, it wasn't easy.  So I *can't*
write a good tutorial for new users, because I don't remember what the hard
part was.  But Mark may be able to write a tutorial for people who don't
care about Git, and just want to work on LilyPond.  If he can, and it's
useful, I think we should find a place for it.

Thanks,

Carl


> 
> Best,
> John