Re: improving the CG

[Mark Polesky]

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.

**********

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.

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


 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)

CG_index_2.txt
Description: Text document