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)
