Re: example files (was "Re: SATB 2-staff template and request for suggestions")

[Kieren Richard MacMillan]

Hello, all --

Han-Wan wrote:

> (stretching the analogy).  I think it is better to just have a simple
> portable bookcase as a demonstration.

Actually, as you probably know, reverse engineering is not easy (for 
most people) -- it's the PLANS that are the most helpful, based on most 
people's learning patterns.

> The problem is in the number of examples. We already have about 400
> small examples, and I think they're already hard to navigate. If you 
> want
> to show all the combinations, the number of files goes through the 
> roof.

Only if you do a strict permutation/combination; that obviously doesn't 
make sense.
What makes sense to me (and, perhaps, no one else?) is a dozen or more 
"standard" examples -- like the Satie and Schumann pieces, but widely 
ranging in "purposes", and intentionally developed as teaching/learning 
aids -- used as step-by-step guides.

Jan wrote:

> There are more problems with "intermediate examples": they cannot be
> used for simple documentation or 'regression testing', where one
> feature is tested, explained and indexed, they need to be actively
> maintained, and by cramming too much complexity in example files it's
> easy to scare new users away.

Agreed, 100%: we need the simple documentation (as is) and the 
regression testing models (as is).
IMO, what we *don't* have are a lot of well-documented examples of 
larger (not necessarily complete, but well fleshed out) "projects".

Nick Busigin wrote:

> Having a collection of well documented/commented complete examples
> (bookcases) is a very good idea.  Fortunately such a collection exists:
> the mutopia project:

I agree that this is a good place to start. However, unlike Nick, I 
have not found the Mutopia examples to be "liberally documented", and 
certainly not in an "instructional" style (but rather in an 
"informative" style -- a very different thing).

I am planning to turn as many of my own engravings as possible into 
true instructional models, and, if time permits, take some well-chosen 
Mutopia examples and do the same. Now that I'm a Lilypond "apprentice" 
(i.e., one step up from a newbie) -- on the road to "journeyman", 
"craftsman", and eventually "master" -- I am going to make sure there 
are more examples to help those after me than I myself have found at 
this stage.

Onward and upward!
Kieren.