Re: Another documentation issue

[Graham Percival]

On 19-May-05, at 11:06 PM, Stephen wrote:
> If Lilypond is meant to demonstrate the art of music engraving, if it 
> is meant to recapture a lost art as it was practiced before the 
> computer age, if it is meant to improve musical performances, then it 
> should educate the user rather than allow the user to dictate to it. 
> Meaning there is a downside to Lilypond being bigger and more powerful 
> and more responsive to the user's demands. The vast majority of the 
> time, bigger is better. But the average user may not be an expert 
> music engraver and would make mistakes if Lilypond let him.

Have you read some LaTeX manuals?  If not, I highly recommend reading
one; have a look at the discussion about margins.

Changing the margins (at least, making it "1 inch" as is common in 
Word) isn't
recommended from a typographical point of view.  But many users want 
that
(at least when they first begin using LaTeX) -- including myself.  
Mostly because
I was using it for university essays, and I knew that everybody else 
was using
Word (with small margins) and I didn't want it to look as if I was 
padding my
essays.  :)

My point is that LaTeX lets the user do whatever he wants (including 
shooting
himself in the foot), but the manual warns the user not to do so.  
LilyPond should
do the same thing.  Any education of the user should happen in the 
manual.  Now,
if you have any specific recommendations for user-education, please 
tell me.  I'm
always happy to include people's patches to the docs.


> I don't see a clear definition of what constitutes an improvement of 
> Lilypond or statement of purpose other than what I read in the 
> introduction,

OK, that's enough.

LilyPond is an open-source project.  The contributors, be it Han-Wen 
and Jan working
on internals, Mats answering questions, or me writing docs, work on 
whatever itch
they want to scratch.  I'm currently editing the "basic notation" 
chapter.  Not because
I think that's what the docs need the most (that would probably be 
clarifying the
"global issues" chapter), but because I'm a neat freak.

You may also want to read "Cathedral and the Bazaar", by ESR.  That 
deals
with the whole "leadership" issue.

>  Which I don't understand, because I think it is more exciting to 
> develop a program which is more specific, rather than, say, a notation 
> program.

Patches, be it to documentation or code, are always appreciated.  Let 
your excitement run wild.

- Graham