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--
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
