Re: Volunteering with LilyPond

[Eyolf Østrem]

On 06.01.2008 (09:51), Reilly wrote:

> No offense to everyone who has worked on the documentation for Lilypond, but 
> the documentation is the weakest component of the package. The index often 
> lacks entries for my questions. The entries more often than not, do not 
> address my problems. The coded examples are often "too clever" and don't 
> illuminate my ignorance. Obviously everyone wants to make the documentation 
> equal to the programming. That is why the GDP is underway.

Hopefully, the GDP will be able to remedy some of this. As one of the
rewriters of the Notation Reference (in fact the *only*, AKA "Mr Zero"), I
can subscribe to some of the criticism. I don't know about the index -- I
hardly ever use it, perhaps for the reasons you mention -- but as for the
examples, it has been my guiding principle that if I don't understand an
example, down to the details of "why does this setting do that, why does it
have to follow this syntax?", it needs to be rewritten. I've tested all the
examples I've been through so far according to that principle. 

To some extent, this runs counter to another documentation principle which
I've reluctantly, very reluctantly come to accept, if not endorse: since
all the music examples are updated automatically with convert-ly if syntax
changes etc. are introduced in Lilypond, the explaining text should not be
too directly tied to the examples, since it will then require quite a lot
of extra effort to go over all the text that is NOT automatically updated,
and this is a constant risk of error. I don't like it, but I see the
rationale. 

>
> Suggestion:
>
> Collect a team of "Lilypond MUSIC Consultants." This could be the general 
> lilypond-user group or a subset. Volunteer members would agree to answer 
> questions. The GDP team should *not* spend time researching answers to 
> musical or notational questions IF they can find a "local Lilypond user" who 
> knows the answer. For instance, take the questions below:

Re. your 
>
> What is a fall?
> What is a doit?

example, the problem is not so much knowing what it means -- that can be
looked up quite easily -- but to know (a) what kind of variations does a
user expect? does size matter? angle? are different symbols or styles in
use, and are they informative variations, etc.; (b) figure out how to
effect all these variations through Lilypond code; (c) choose how much of
this is really needed in the docs, and how much of it can be written
meaningfully without violating the "don't comment the examples directly"
principle. 

Your suggestion of a group of music consultants is fine, and I intend to
try to distribute some responsibility along similar lines when we come to
the Specialist notation chapters (so that Graham would not have to write
the guitar section), but I fear that such a group would tend to become too
loose (volunteers come and go), and it would probably be too much of a
hit-and-miss thing -- can I expect to have a sax player in the group when I
write about doits? Maybe, maybe not. It is probably more practical if
people write in with concrete suggestions if something is missing, wrong,
or unclear in their particular field of expertise.

> A general *alert* to the GDP team: music notation is NOT standardized. 

We know that...

> I am conflicted in 
> regard to notation. I want to keep the flexibility of Lilypond to tweak the 
> output to my needs. Yet, I want to introduce some consistency in output to 
> improve the quality of printed music for all the composers who don't want to 
> tweak their output. I think minimally this would require a number of style 
> sheet packages (like LaTeX packages) which (a) address all the issues 
> appropriate for the intended output (e.g. contemporary conducting score 
> style sheet; contemporary study score style sheet; contemporary condensed 
> score style sheet); and (b) at the same time, make the issues user 
> tweakable.

Yes, and as Graham pointed out in another thread, this is perfectly doable
-- it just takes someone to do it. I'd love to be able to write
\rehearsalmarks{alphabetic} or \setlenght{betweensystemspace}{2em} if
someone writes a package that includes it. 

Eyolf

-- 
"`...we might as well start with where your hand is now.'
Arthur said, `So which way do I go?'
`Down,' said Fenchurch, `on this occasion.'
He moved his hand.
`Down,' she said, `is in fact the other way.'
`Oh yes.'"

- Arthur trying to discover which part of Fenchurch is wrong.