Re: Volunteering with LilyPond

[Graham Percival]

On Sun, 6 Jan 2008 14:21:15 -0500
Reilly <address@hidden> wrote:

> Eyolf,
> 
> On Jan 6, 2008, at 12:00 PM, address@hidden wrote:
> 
> > example, the problem is not so much knowing what it means -- that
> > can be
> > looked up quite easily

It *can be*.  But *I'm* not going to bother.  Why should I?  I
don't know the instrument, I don't care about the instrument; if
the users of that instrument can't be bothered to help, then I
won't be bothered to write docs for them.

A very real example of this: vocal music.  Yes, most users of
lilypond are vocal people.  But I'm not.  So I've never edited the
"Vocal music" section -- despite the fact that it's the most-read
section.  How do we do divisi lyrics?  How do we align syllabels
to notes?  I don't have a clue, and I don't care to have a clue.

(at this point, nobody can seriously accuse me of being lazy or
unhelpful, so I have no trouble being completely blunt about this)

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

These are also important...

> Perhaps I misunderstand the purpose of Graham's example question. The 
> quality and useful of answers would depend on asking the RIGHT 
> questions.

... but Reilly understood exactly my point.

Here's an example -- the *only* example :) -- where I play the
part of the helpful user.  We'll pretend that Trevor Daniels
(vocal guy) is editing the Orchestral string section.

Trevor: What's this "artificial harmonics" garbage?  Aren't all
harmonics naturally occuring?
Graham: It means you put two fingers on the string; the lower note
is notated with a normal notehead, and the upper one is a
harmonic.
Trevor: cool.  Like this?  <a cis\harmonic>4 ?
Graham: oops, sorry.  No; it needs to be a fourth or a fifth. Like
this
  <a d\harmoinc>2 <bes ees\harmonic>2 |
  <a e\harmoinc>2 <bes fes\harmonic>2 |
Trevor: thanks, docs updated.


(ideally I would have included the lilypond exapmle in my first
reply, instead of waiting for another question from Trevor)


If I didn't reply, Trevor *could* have found the answer.  Maybe 15
minutes googling for the definition of artificial strings, maybe
10 minutes of figuring it out in lilypond... but as somebody who
_knows_ orchestral strings, it only takes me 60 seconds to bash
out a quick example.  That saves Trevor almost half an hour of
stumbling around in the dark -- all the while thinking "this is
stupid, a string player should be doing this stuff".

Oh, and I could also point out Stravinksi's customary "print the
actual sounding pitch in a small black notehead above the two
existing noteheads" trick.  Again, that's something that's trivial
for a string player, but not at all obvious to a vocalist.

> In my experience, it is almost always more
> informative to ask someone who is an "expert of sorts" in the area I
> am confused. 

Exactly.

> I think we disagree slightly on how my proposal would work (or, 
> perhaps, how people behave). If I have to notate a classical guitar 
> passage and I consult the Lilypond documentation and I find it 
> inadequate, it is expecting a lot of my --- aka, the casual music 
> engraver --- to rewrite the documentation and send it to
> "somebody." (I don't even know to whom I would send it.)

After a bit of searching, you'd find
http://lilypond.org/web/devel/participating/documentation-adding
which directs you to either me or the -devel list.

But yes, it *is* asking a lot.  That's why we're doing GDP: a
limited-time push to seek out anybody who could contribute (or
simply be consulted), so that we can ask questions in advance.

Cheers,
- Graham