Gianmaria Lari <gianmarial...@gmail.com> writes:
> On 13 April 2018 at 10:00, David Kastrup <d...@gnu.org> wrote:
>
>> How about pointing out what you find hard to understand in the
>> documentation then?
>
>
> I'm not a musician and I'm a young lilypond user. So I don't like come
> here and say that this part of the documentation is not clear even if
> I would specify that it is not clear *to me*. Report this type of
> things is difficult without hurt the persons that write the
> documentation work.
The point of the documentation is not to look pretty. It is also not to
explain things to masters of deduction and LilyPond: those will just
look in the source code of LilyPond for a definite answer.
A lot of pain goes into the documentation _exactly_ so that people have
a dependable, infinitely patient and replicable resource for learning to
work with LilyPond without requiring personal assistance.
Pointing to it is for the sake of making people stop asking questions
and start working with LilyPond. Not for making people stop asking
questions and stop working with LilyPond.
One surprisingly hard lesson to learn as a project lead is that "it's
too hard for me to understand" is perfectly equivalent to "it's too hard
to understand" when I can consider myself to be part of the core
audience, whether we are talking about code, comments, or documentation.
There may be better ways to sugarcoat stuff than I manage, but in the
end it boils down to any material needing to be able to be accessible to
its core audience. More often than not, that requires several
iterations, partly because the people initially writing the
documentation are too intimate with what they are writing about to
properly channel their core audience.
If you have to fight tooth and nail for any bit of feedback, that
doesn't help.
> And of course, I appreciate who made the effort to write it.
>
> Regarding the example in the documentation: here it is.
>
> test = { \tag #'here { \tag #'here <<c''>> } }
> {
> \pushToTag #'here c'
> \pushToTag #'here e'
> \pushToTag #'here g' \test
> \appendToTag #'here c'
> \appendToTag #'here e'
> \appendToTag #'here g' \test
> }
>
> I simply don't understand it. I don't understand it because: it is too
> long, there are too many things, I don't understand the example goal, and I
> don't understand the explication following the code.
It adds material at two points to \test: in the inner parallel music,
and the outer sequential music. The first version adds successively g',
e', and c' at the front of those expression, the second at the end of
those expressions.
Ok, it is probably trying to show to much at once. What's the scope
that you think you could deal with? Two separate examples for
sequential and parallel music (probably not a good idea to work on
multiple tags here)? Not adding more than a single term?
But then my above simple example prompted by you only added a single
term and you stated that this was not what you considered helpful.
> But I'm sure, this is very probably my specific problem. Of course, I
> could spend some hours on it and discover how \pushToTag works, but,
> well, you can't do this for any things like this to discover that you
> don't need this commands :)
So instead I spend hours on explaining and the documentation stays the
way it is, so we get that discussion with the next person next time
round? I'd rather get the documentation problem solved if I am
investing that amount of time.
> So this is why I avoided to complain about the documentation.
--
David Kastrup
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user
