Re: improving the CG

[Carl Sorensen]

On 12/25/09 8:13 PM, "Mark Polesky" <address@hidden> wrote:

> Carl Sorensen wrote:> As I think more about this, I wonder if there should be
> a
>> short and sweet summary for experienced Linux developers,
>> followed by a gentle (and longer) introduction for the
>> Windows guys.
> 
> Actually, I'm thinking there should be a short and sweet
> summary for the GUI-based contributors, followed by a
> different (and longer) introduction for the Git-based
> developers.  I think most of the essentials will be visible
> just by skipping the paragraphs (which wouldn't be _that_
> long) and looking only at the command-line examples, which
> would have everything the experienced devs would need.

I still think you should have a quick-start guide for people who are already
experienced with Linux development and git, so that they can quickly find
out what is special/unique to LilyPond development.

> 
> **********
> 
> Some more thoughts about restructuring the CG...  I finally
> looked at the lilycontrib app and, well it's pretty awesome.
> Has anyone written any documentation for it?  I could
> probably do it if nobody has yet, since I'm already looking
> at the rest of the CG.
>

I'm glad you think the LGCG (LilyPond Git Contributor's GUI) is "pretty
awesome".  You have Graham to thank for that, as he kept the development
focused.

There is *no* documentation for the LGCG.  You're welcome to write it.  I
wasn't planning to.

BTW, the reason I call it LGCG instead of "the GUI" is that there is a git
GUI (you get there by typing "git gui" at the command prompt), and I don't
want to have those two confused.


 
> Anyway, regarding comments about `short and sweet' vs.
> `diluted with fluff'...  I'm writing some text intended for
> serious would-be developers that makes no assumptions about
> previous development experience.  It won't be fluff (I'm
> aiming for clarity not length), and it won't be required
> reading for GUI contributors.  But it will explain (with
> modest clarity, I hope) some of the currently missing
> elements involved that may be common knowledge among more
> experienced developers.
> 
> If I organize the chapters efficiently, this text would be
> in a place where it won't scare away GUI contributors with
> details they don't need.  But these `details' will be
> valuable to those interested in a deeper level of
> development involvement.
> 
> I feel that it has taken me longer than it should have to
> get familiar with some of the basics of compiling, so this
> text would ideally reduce the confusion time for new
> developers.  The idea is not just to get more contributors,
> but to make it easier for more contributors to become good
> developers.
> 
> I've attached an updated (but still unfinished) index
> proposal.  The less detailed version follows below.
> 
> Let me know if you have objections to the outline.  Also,
> the introduction that I first proposed* would be changed to
> more clearly reflect the options available (ie. Graham's
> insistence that "you don't need Git to contribute").
> Furthermore, some of the `scary details' would be removed
> from the introduction and moved to the `Using Git' or
> `Compiling' chapters.
> 
> *http://lists.gnu.org/archive/html/lilypond-devel/2009-12/txt0Sx9cyLDKu.txt
> 
> One final note about the current proposal:  Chapter 3 `Using
> Git' looks like it'll be quite long this way.  I'm
> considering splitting it into two chapters, but I've not
> made up my mind about it.
> 
> Comments appreciated.
> 
> - Mark
> 

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).

> 
>  1. Introduction to contributing
>  2. Using the `lilycontrib' GUI
>  3. Using Git
>  4. Compiling
>  5. Documentation work                             (3)
>  6. Website work                                   (4)
>  7. LSR work                                       (5)
>  8. Issues                                         (6)
>  9. Regression tests                               (7)
> 10. Programming work                               (8)
> 11. Release work                                   (9)
>  A. GNU Free Documentation License                 (A)

Thanks,


Carl