Re: Examples (for the web site and complete scores) status

[Graham Percival]

On Wed, Aug 05, 2009 at 07:57:52PM +0200, John Mandereau wrote:
> The new directory Documentation/examples that was proposed to host
> examples for the web site plays a duplicate role of input/ and
> input/mutopia.  What about cleaning up these two directories (that is,
> deleting unused input files and cleaning up makefiles) and use input/
> instead of creating a new directory that would mostly have the same
> purpose?
> 
> BTW what about keeping existing examples in input/mutopia in another
> page named e.g. "More examples"?  OK, that's not very inspired; if there
> are good reasons for not keeping these input files, let's just junk
> them.

IMO, there are two kinds of examples here.
1)  advertizing examples: "we can do tabs, complex rhythms, lots
of accidentals, gregorian chant, etc etc".  We expect people to
glance at the image and then move on.
2)  educational examples: part of the documentation.  We expect
people to read the source if they're interested.

I do not think that we should mix #1 and #2.  I want the
web->Introduction page to simply be an introduction.  Once
somebody has decided to use lilypond, they should never look there
again.  Also, I want to keep those pages simple, and if possible,
direct the reader through them.  The "Where next?" sections are an
explicit way of doing this.

Now, I asked Jonathan to look through input/ and input/mutopia/
for anything worth keeping for the website.  I assume that he's
done so, so evidently nothing there fits into category #1.  If you
think he missed anything cool, then by all means we can add
another item to the Examples page.

If somebody thinks we should show longer example(s) to aid our
"advertizing" efforts... I'm not *completely* opposed to splitting
Introduction->Examples into "Short examples" and "Long examples".
I'm currently against such a move, since it would disrupt the
current "flow" of the Introduction pages -- again, I believe that
the best way to improve the readiblity of those pages is keeping
them as simple and non-verbose as can be reasonably achieved with
our human potential without an unduly strenuous amount of effort
or overly long temporal span.
(sorry, my meta-humor got away with me)

That said, I'm willing to listen to counter-arguments about why we
should add long examples to the advertizing pages.


As for category #2, we already have a great location for pieces of
input: the snippets.  If there's anything of educational value in
input/, let's put it into LSR.  We don't currently have a
"complete pieces" or "long examples" or whatever tag, but I'm sure
Valentin would love to add one.  I think it's important that, once
users get expectations about the docs+website, we meet those
expectations.  One expectation is that examples of input notation
are in the Snippets.

Cheers,
- Graham