new documentation

[David Bobroff]

I've only had time to skim the posts about the _New and Improved
Documentation_.  Most of what I remember from them seems to focus on how
to structure it, what to put in and how to arrange it.  As a novice user
of Lilypond what I think would be important would be a way to find the
useful information that is already there.  Often the answer to a post
(many of them mine) is look here:

http://www.lilypond.org/answer-to-your-question/

While some of the information found is indeed of use, it is often
difficult for new users (me, at least) to grasp in this manner.  That
is, theory first then apply it to your problem.  I find it much easier
to see an example of something like what I'm trying to do and see how it
is done and then make use of the method.

I understand it is likely impractical to give an example for
everything.  For many things a simple description of what it does and
how to use it would be sufficient.  Finale, no matter what you think of
the software, has rather good documentation.  The three-volume printed
set of documentation, while it seemed intimidating to some users,
actually made learing to use the program quite easy for me.  The best
feature of this was the extensive index which made it possible to look
up almost anything I wanted to do and provided me with a location for
the information.  For example, a question I asked not long ago had to do
with the global setting for the MultimeasureRest number position.  I was
instructed by Mats to look at some particular place in the docs, and
after studying it for a few minutes I had my answer.  Without being told
where to look I would not have found it.  That is what a good index
does, it tells you where to look.  It would have been very intuitive to
see and index entry something like:

******

Rests
        multimeasure see--> MultimeasureRest

******

MultimeasureRest
        \markup
                positioning
                        global
                        local

...and have a link to the place in the docs with the information, with a
short description of what it does.

Questions about the web-doc:

I think it was Han-Wen who mentioned that web-doc build failures should
not be reported here.  Should that be on lilypond-user?  The current CVS
(1.934) builds just fine but 'make web-doc' exited with an error (yeah,
I just reported it here, but I'm trying to find out where I should
report it).  Also, how often does the web-doc change?  With each CVS
update or with some of them?

-David Bobroff