Re: Why not have a Lilypond documentation set arranged as layman's Q: does LP do this?

[Andrew Bernard]

Hello Ken,

I also use Dorico, which currently has a 1720 page PDF manual. If I may 
make a few comments. There's an active Steinberg Dorico forum. It's 
continuously full of complaints about using the manual. It's also full 
of complaints saying Dorico is not 'intuitive'. Finally somewhat annoyed 
by this Iast week I started a topic about the term intuitive as applied 
to software, linking to a very good short essay on the subject by one of 
the developers of Ardour. What people seem to mean by 'not intuitive' is 
that they actually have to make some effort to learn an immensely 
powerful and rich program.

Now, this thread got hijacked into endless complaints from users saying 
they can't find what they want in the manual, and dozens of different 
reasons given. Some want an index with dozens of synonyms for terms so 
they can 'find things'. Others don't like the structure of the manual at 
all. Some are offended that the manual explains things that any educated 
musician obviously knows. Some are offended and upset that the manual 
does not cover every single possible use case for a vast engraving 
program. It goes on and on. The manual is written by one dedicated full 
time staff member. It's an amazing effort. I think it is truly 
remarkable as documentation, yet when it does not conform to what a user 
expects. they whine on the forum.

Why am I telling this? Because it highlights the problem with software 
manuals. They are _never_  going to satisfy everybody, partly because 
people are at all different levels of musical/engraving experience, and 
it is impossible to have a single document target all levels of user at 
once.

To address this common issue back in the days when people read books, 
there was a publisher that made a series called 'The Missing Manual'. 
These books were great - the had a lot of material not in the basic 
documentation, and I think that was a good idea.

So the problem with your present suggestion is this, based on my 
experience with Dorico and the complaints. Every layman seems to have a 
different 'layman's term' for things, some of which are true 
alternatives and some of which are just plain wrong. There's an infinity 
of layman's terms, and no matter how diligent you are you will be 
forever adding more. An endless job. Sure adding some may be good, but I 
think this project is fraught with difficulties. For example, as 
somebody who sets a lot of modernist music, I'd be asking questions like 
'can Lilypond do beams on a single note that extended across several 
pages indicting duration?'. That's probably not the sort of question you 
could come up with on your own. And so on for a hundred other things 
about modernist music engraving.

Lilypond has good documentations. The concept of a good tutorial 
introduction combined with a Notation Reference Manual I believe works 
well. Remember the NR is a reference not a guide. It's identical to the 
UNIX manual. which is pure reference - always has been.

Make no mistake, I don't think this is a bad idea, I just think its 
problematic, you will have to deal with complaints forever, and it 
requires a lot of resources to compile and maintain, which is something 
the Lilypond dev community does not really have. There's also the 
problem of maintaining this in many languages.

My answer to this is unpopular, of course. With complex programs there 
is no substitute for dong the hard yards and just reading the manual all 
the way through, over and over, regularly. That's how I learned UNIX, 
and that's how I learned Lilypond. I know from the Dorico forum people 
don't like to do this hard work nowadays, expecting instant answers to 
everything. In addition to this, the superbly helpful user list here 
serves as the missing manual when you hit problems or fail to grasp a 
concept.

Finally, there has never been a Lilypond book. That would help a lot, 
but a huge proposition. Also, Scheme is a stumbling block for many, as 
laypeople don't know it and even many programmers have not been 
introduced to it. There are a couple of Lilypond Scheme tutorials, and 
with no disrespect to the authors, they are only the tip of the iceberg. 
That in itself is a big area of Lilypond, as one the principal virtues 
of Lilypond is it's extensibility, which differentiates it from programs 
like Dorico. So more Scheme information as it relates to Lilypond would 
have to be included I reckon.

I don't think, as you say, your question is dumb, and in no way intend 
to diminish it with my comments. I just think this is what I call a 
'hard problem.'


Andrew


On 18/08/2022 12:16 pm, Kenneth Wolcott wrote:
> Hi;
>
> Dumb documentation question here:
>
> Kind of like a FAQ but also kind of like an index.
>
> So this would be a "translation" of layman's terms to
> Lilypond/professional terminology and an index; it could even point to
> existing indices (in Notation) and/or the Glossary.
>
> Q: Does Lilypond do X (layman's term/phrase)?
> A: Yes, and this is the Lilypond description/verbiage/etc...
>     see Learning (precise section URL);
>     see Notation  (precise section URL);
>    etc (Glossary, Snippets)