Trevor Bača wrote:
OTOH, I really do believe that the reason most
users walk around without a solid model of file structure (or score
structure) in their heads isn't because chapters 3 - 5 (which are
*amazingly* helpful and huge improvement over the previous manual,
which was essentially silent on these points) are in some way
deficient, but instead because the vast majority of actual lily code
which users (both new and experienced) look at simply doesn't
*reinforce* that file structure. See below ...
I disagree. (sidenote: there's info about file structure in chapter 10
as well, which is linked to in chapter 3 I believe).
Let's do this logically:
1) experienced users understand the structure.
2) the purpose of the documentation is to allow an interested,
reasonably intelligent, inexperienced user to do everything an
experienced user can do.
3) interested, reasonably intelligent, inexperienced users do not
understand the structure.
4) the documentation is flawed.
I have no difficulty admitting that the docs are flawed ("flawed" = "not
perfect"). If #3 is true -- and I admit that I do not currently
believe* that is _is_ true -- then the docs should be improved. By now,
everybody knows how to do this.
* I don't have a lot of evidence to back this up -- but then again, I
doubt that other people have evidence to counter this claim.
Carl:
I think if you asked 100 novice users of LilyPond about that
relationship, fewer than 5 could articulate it.
Trevor again:
Are users willfully ignoring 3 - 5?
My belief? Yes.
Look, LilyPond is complicated. Before a new user starts doing serious
work, he should read AT LEAST chapters 2, 3, 4, 5, 6, any relevant
sections in 7 and 8, 10.1, 10.2, 11.1, appendix D, and know that
appendix G and H exist.
That doesn't include any fancy things like \override, scheme, or
changing the spacing. All that documentation -- probably about 100
pages of printed material -- just to properly write basic music syntax
with the default output, without shooting himself in the foot by doing
things incorrectly.
That's a lot of stuff to read. A _lot_. I've been experiencing similar
pains: in the past year, I've written non-trivial programs (with little
or no previous experience) in ChucK, perl, java, C++, python, and QT
(not a language, but still requires a lot of doc-reading). I've had to
read a lot of documentation, and sometimes I've wanted to scream -- if I
know how to something in perl, why should I spend an hour reading the
python tutorial to figure out how to do in it that language?!
But there really isn't another option. Programming languages are
complicated. Fully-featured layout languages are complicated. You
can't do anything (serious) in LaTeX without having a heavily-used pdf
of "the short guide to LaTeX" on your desktop.
I don't blame users for ignoring chapters 3-5... but at the same time,
I'm not going to wring my hands in sympathy for them. The information
is there. Could it be improved? Sure. All documentation suggestions
are welcome. Would it be easier for new users if every lilypond example
were constructed in the same way? Yes, definitely. When I started
writing Appendix D, I tried to make each template with the same style.
But there's a lot of examples that need to be updated, and I don't have
much time.
If anybody wants to volunteer to do a clean-up of the manual and LSR
snippets -- I mean, cleaning up the LSR snippets to a higher level than
I think the LSR maintainer should do -- then I will enthusiastically
accept your help. Budget at least 50 hours for this task.
Cheers,
- Graham
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
