Re: Another documentation issue

[Stephen]

> Have you read some LaTeX manuals? >

Yes, I think reading a LaTex manual might help me understand Lilypond a 
little better in other ways too. I know C++ and studied Lisp a little; Tex 
is the third rail.

But as a windows user, I just downloaded tetex-src, tetex-texmf, and texinfo 
on which Lilypond is based. I made an abortive attempt to compile Lilypond 
on windows using msys and decided my time would be better spent learning how 
to use Lilypond rather than compiling it. Is the LaTex manual in the tetex 
sources or is that something else? What is the difference between Tex and 
LaTex?

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

Yes, it takes someone like you to edit the documentation. Editing is all 
about being detail oriented, which is a good thing if you choose the right 
task as you have. Eventually, you will get to all of it. I think every 
detail in the documentation is important, because a newbie who is trying to 
understand Lilypond for the first time will tend to read into things a 
little too much in an attempt to understand. The early chapters are 
especially important because once someone has gotten into the manual a 
certain distance, you can assume he is not a newbie anymore.

Right now, I am stuck on 'Internal music representation'. I don't think it 
is as clear as it could be. If I knew for sure, then I'd understand it and I 
wouldn't need anyone to clarity it for me. So if anyone who is knowedgeable 
agrees that it could be clearer, please do. I could be wrong, I am sure if I 
just plugged away and read the whole chapter, I would understand it.

I have read the 'Cathedral and the Bazaar' and I do approve of that 
approach. The downside is if the developers work against each other because 
they do not have a common understanding of what the software is meant to be. 
I don't think of a leader as someone who has to have all the ideas and all 
the answers, which is sadly what most people associate with that word, but 
just someone who defines the goal and enjoys getting input from others on 
how to reach that goal. Anyway, the leadership is fine here and the goal is 
clear. I still say that a lot of the clarity stems from the Introduction in 
the documentation rather than, say, developers reminding each other of it or 
putting it in that context on a case by case basis. I am a very literal 
person who likes things to be terribly explicit, most people do not need 
that, so I understand there is no real issue here, it is just that my 
communication style differs from others.

Stephen

----- Original Message ----- 
From: "Graham Percival" <address@hidden>
To: "Stephen" <address@hidden>
Cc: "lily-devel" <address@hidden>
Sent: Friday, May 20, 2005 2:33 AM
Subject: Re: Another documentation issue


> 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