Re: improving the CG

[Carl Sorensen]

On 12/26/09 7:14 PM, "Mark Polesky" <address@hidden> wrote:

> Carl Sorensen wrote:
>> Have you considered whether "Using Git" should be an
>> appendix?  To the extent that it's teaching about git,
>> rather than about LilyPond, it might belong in an
>> appendix.
>> 
>> Maybe there should be a chapter called something like
>> "Contributing patches" that mentions all the possible ways
>> of contributing patches, and then appendices describing
>> various ways (diff, git, lilycontrib.tcl).
> 
> 
> Okay, I tried revising the structure to accommodate some
> suggestions, but I can't find a way to move the Git stuff to
> an appendix without creating awkward continuity issues.  For
> example...
> 
> These nodes could reasonably be moved to an appendix:
>   Starting with Git
>   Basic procedures
>   Advanced procedures
>     Git log
>     Applying remote patches
> 
> But these LP-sepcific nodes would have to stay in chapters:
>   Downloading branches
>   Advanced procedures
>     Working with remote branches (current 1.4.3)
>     Pushing to git.sv.gnu.org

For  me, it seems that Starting with Git and Git on Windows both go in the
Appendix.  I'd even have detailed instructions for the LP-specific stuff in
the appendix.

The LP-specific stuff for the beginner could profitably be put in the
appendix, in my opinion.

The stuff that it LP-specific for the Git veteran just needs to describe
the branches that are used and what they're used for, IMO.

So for your index, I'd put all of section 2.2 in the appendix, with a 2.2
that says "this is what you need to get, and if you don't know how to do it,
see the appendix" to replace it.

I really like what you're doing in terms of making git accessible, and
helping git newbies figure out what to do.  I remember that as a very
frustrating time, and you're helping resolve the frustration.

But we also have some people coming who are experienced in Linux development
and in using Git (probably more of those all the time).  We don't want to
bury them in tutorials if we can avoid it.

But if you write what you would have liked to have had, then it will be
available for the next person like you.  And whether it goes in an appendix
or in the body of the CG can be resolved later, IMO.

Thanks,

Carl