Re: How do new users feel about LilyPond's documentation?

[Carl Sorensen]

On 4/22/15 1:30 PM, "Martin Tarenskeen" <address@hidden> wrote:

>Stiil, I will try to give a sketch what happens to me again and again:
>
>I want to learn about how to change defaults and how to tweak default
>output so I open the Notation Reference:
>
>Notation Refence -> 5. Changing Defaults
>" A tutorial introduction to accessing and modifying these properties can
>be found in the Learning Manual, see Tweaking output. This should be read
>first " -->

I think this appropriate for a reference manual.  It should point you to a
tutorial, if you need the tutorial.

>
>Learning Manual -> 4. Tweaking Output -> 4.1 Tweaking Basics
>->4.1.1 Introduction to tweaks
>
>"Before starting on this Chapter you may wish to review the section
>Contexts and engravers, as Contexts, Engravers, and the Properties
>contained within them are fundamental to understanding and constructing
>Tweaks." -->

This is a potentially bigger problem, because the Learning Manual is not
intended to be a reference manual.  But it *is* intended to be read
sequentially.  Maybe we should leave this particular paragraph out, or
change it to read "If you have trouble understanding this section of the
manual, you may wish to review Contexts and Engravers."  That way, you're
providing some help, but not asking the reader to go there directly.

>The end of the story is: I have read a lot of interesting stuff and learnt
>a lot, but still don't know how to make a particular tweak or change some
>default setting. 

If the manual were to show you exactly how to make every possible
particular tweak or change every possible default setting, it would need
to be many times longer than it is.  The goal is to help you understand
how to use the manual to find your specific tweak.

I'm sure there is much that can be done to improve the situation, but I
don't think it is to develop an exhaustive list of "How do I change X?"

Thanks,

Carl