The documentation for Lilypond has one problem; it is, as the program is itself, under development. It is screamingly frustrating for us non-programmer users. However, that said, it is changing because it is not nearly finished, it is required to print many different kinds of music.
The Learning Manual was scarcely present when i started using Lilypond. It has changed and is continuing to change. That is frequently frustrating because things you knew were in a certain spot get changed. Sometimes its like quicksand. The ground changes beneath you as you walk on it. But that is life with a program under development.
Even having read the Learning Manual, applying it in different situations is not always easy. Personally I have found that asking the question on the mailing list is not as helpful as spending a little time struggling with the problem. Most of the time I find solutions.
Unfortunately, what I need Lilypond for isn't small projects. So even If I've gone through the Learning Manual start to finish, its still like I've been thrown into the deep end of a swimming pool and told to swim. As you can see, I haven't drowned yet. There's lots I don't understand yet but I'll get there.
Since I usually am working with piano music, I have found that working with a 4 voiced template to begin with is the best way too go. Most piano music is basically four voiced music despite what you may see on the page. I learned that by working with it over a period of time. No one told me that.
Because, the improvements being made to Lilypond are occurring in the development versions I have found that using them has been the best way for me to use Llilypond. That will not be true for everyone. Everyone's experience with Lilypond will be different. I know I learn best when I am working hands on. I don't learn very well from manuals with theoretical examples. So I've adjusted how I work with Llilypond to account for that. I use the snippets library a lot. Lots of the time the things I want to do are out of the ordinary anyway, but that's life with Western European Music. It is extremely complex.
Call this a rant if you want, but I do not mean it as such. I'm just stating that the Lilypond documentation is not perfect, it is changing almost as we speak and patience with it is required. From the very little I have encountered with GUI music notation editors, they are not much easier than Lilypond. At least with Lilypond you can get some quick impressive results with just an editor and a command line.
Scheme just frustrates me. Everytime I think I've gotten a handle on it there's a curve ball thrown at. Obviously I haven't grasped it quite yet. I'm not letting this stop me from completing projects though --- I just keep going and learning a little more each time. Patience is what is required. Despite my lack of understanding, I have managed to complete some pretty complex scores on my own. I'm just stubborn enough to keep at it.
The reason that adult beginners hardly ever do well when learning to play the piano isn't because their fingers cannot do what is required, they fail because they are not patient enough to keep practising simple things until their fingers acquire the technique to do what their minds have already learned. I think Lilypond is something like that. In both cases, patience and some dogged determination are required to learn the skills needed to do what you want.
One other thing, much of the time I have questions, but do not know how to ask the question. That is extremely frustrating and I don't know if there is anything you can do about it. Sometimes i just don't know the correct terminology to use. Many things that are assumed when you are playing the music are not assumed when you are typesetting the music. I've tripped over that one many times.
Lilypond isn't perfect, recently the way Lilypond works with Jazz chords and lead sheets has undergone drastic change. This was a matter of those who knew something some of the developers did not know or understand taking the time to explain how things worked in real life. It is difficult to tell an expert that he may be wrong about something. Choosing words carefully gets good results, rants almost never get the required results.
I don't like the quicksand any more than anyone else, but considering the state of the program, that is the way things are. Enough said.
cheers, davidf
-- David Fedoruk B.Mus. UBC,1986
Certificate in Internet Systems Administration, UBC, 2003