Re: problems with learning lilypond

[John Sellers]

Graham Percival wrote:
> ... umm, WHAT?!
>
> Are you seriously claiming that you couldn't find the "Learning
> Manual" link?  Top-left on the Documentation page?
>
> 1) go to lilypond.org
> 2) click on "documentation"
> 3) click on "documentation for 2.11"
> 4) click on "Learning manual"
> 5) click on "1.2 About the documentation" or "2. Tutorial"
>
>
> If you can find the documentation, you can find the tutorial.  And
> if you can't find the documentation... well, some programs can be
> used without reading the docs; lilypond is not one of them.
>
>   
You misunderstand me.  I am not concerned about myself.  It is the 
umpteen other newbies who come to the front page of lilypond and are 
confronted with multiple choice, none of which are distinguished from 
each other in regard as to the best one to pick.

If I understood what was said, the 2.11 and later documentation is 
better than 2.10 and earlier.  Why would I look at 2.11 when the most 
recent stable version is 2.10 unless something up front says.  "The 2.11 
tutorial is important and you should look at it if you want to 
understand lilypond."

Is it important?  You bet.  If you have a blatantly obvious link that in 
effect says "here is where to go to get a handle on Lilypond" then 99 
out of a 100 who want to get a handle on Lillypond will follow that path 
and most of them will get a handle on Lilypond.  If there is no such 
link, but instead you say something like "2.11 documentation".  Then 
many newbies may well say.  Hmmmm...2.10 is the newest stable release.  
I'm not going to waste my time on 2.11 because it is not stable yet, and 
thus will never know they missed a tutorial that will save them a lot of 
time.

It is true that if one has enough time, one will look around and 
eventually find that there is a tutorial that one should look at.  But 
this isn't like to happen if one doesn't have a lot of time, which 
happens to be most of those who are technologically involved.

Your comment about "are you seriously claiming..." comment.  Of course I 
can find it, if I know it is there, if I know there something important 
I should see, if I know that it is better than looking somewhere else.  
You described a drill down to get there.  I suggest you count the number 
of end points for all the drill down paths for the depth of the 
preferred documentation and then calculate the time it would take to 
explore them compared to a doing a single click on an front link that 
says: "Learning manual that every person wanting understand Lilypond 
should look at".

You have to remember that the world over, people have different 
experiences and different ways of understanding, and that these are not 
unique or even similar in spite of using the exact same words to 
describe whatever it is.

Let me explain it in another way.  Consider "learning manual" and 
"dog".  You understand both of these perfectly, right?  But wait, then 
what is "dogged", "dog gone it", "dog days", "hot dog stand", "hot 
dog!", "hot dogging"?   These are all very different and if you only 
knew the word dog and didn't know these idioms you would have a hard 
time making heads or tails of what they mean.  Here is a news flash.  
Whatever a "learning manual" is, turns out to be as widely varied as all 
the dog expressions.  A good way to solve this problem is to be specific 
enough that only the right meaning is likely.  This is illustrated by 
doing a google search on, "You ain't nothing but a hound dog".  You will 
find that there are few if any false positives in the 12,000+ hits.  If 
you want your documentation to really be useful, then put in enough 
qualification that all other possibilities are eliminated.  This is the 
exact nature of putting something like "Choose this link to find the 
best documentation for getting a handle on Lilypond" which doesn't leave 
any room for doubt regardless of which part of the world you might be 
from or what your previous experience might have been.

It is the universal tendency of all technical documentation to fail to 
be this unambiguous simply because of the nature of the context that 
documentation is developed.  Assumptions are made based on what is known 
or seen, and unfortunately none of us has the opportunity grow up and 
experience any of the 99.9999% of the rest of the world, so it is very 
hard for us to take this into account so we do what we already know to 
do instead.

--end of tirade--