Documentation (was Re: Resolving "cannot resolve rest collision: rest direction notset"warnings)

[Noeck]

>> So how could this have been made easier?

Hi,

some more comments on the manuals website (rearrangement basically):
http://www.lilypond.org/website/manuals.html

Distinguishing between "regular use" and "infrequent use" is a bit
arbitrary to me. I very very rarely use "Usage". But I need the
"internals" for almost every tweak/override.

For me, it would make sense to sort it from standard use case to
difficult (that would also emphasize which parts require the knowledge
of other parts):
Intro: Text input
Learning
Usage
Notation
Snippets (don't know where to sort it exactly. Why is it different from
LSR?)
Internals
Extending

"FAQ" and "Usage", I would consider as introduction.
One point in the FAQ is: There’s a lot of documentation! Do I need to
read it?
That is exactly my feeling when I see the documentation. Splitting it
into Introduction (including usage and faq) and reference, it would be
clearer that a user usually should read up to the beginning of the
notation reference and then he can decide to stop and look things up
when it is necessary. I think a linear flow of documentation would be
better than too many choices in different boxes.
The following comments would make the doc page easier to read, because
the way it is, newcomers are overwhelmed by the choice of documentations.

Web: Why is there a link to Web? You would not place a "home"-link
there, would you? To me it is just confusing.

"Other material" is no good category, because the don't have things in
common:

* "All" could/should be named "other/older/previous versions".
* "Translated": It is not relevant for the user to see the status of
translations (you can't even get to translated documentations here).
The language links at the bottom of the page are what a user needs here.
* LSR: again why is it different from the Snippets?
* Development: Ok, developers can cope with more difficult pages, but
why not have the same layout for other versions and present docs for
previous versions and development versions consistently (merge "All" and
"Development").
* FDL: I would put this as a statement and not as part of that list and
link the words "GNU Free Documentation License", because most users
won't know the term "FDL" but they can imagine what a Free Documentation
License is.

So this box could be summarized as: other versions and additional snippets.


Please don't get me wrong: The documentation is already exhaustive and
very good in many points. And I know that it was a tremendous work to
get it done like this, because I started using LilyPond 8 years ago,
when it was much harder to learn LilyPond. I just tried to show some
points that make it easier accessible for new users (in my opinion).

Cheers,
Joram