Graham, Mats
I agree the warning about incomplete bars is hard to find - I tried
and couldn't until I searched git, and I wrote it!
There is a section in the Learning Manual, section 5.2 When things
don't work, which I intend to extend to include help about common
errors, obscure error messages or mysterious happenings, like music
running off the edge of the page. I'll begin by moving the warning
on incomplete bars which is currently in section 1.2.5 in the
Notation Reference to LM 5.2, leaving behind a link, of course. I
don't think there are more than half a dozen such errors, so this
could remove the need for a FAQ altogether.
Trevor
Mats Bengtsson wrote Wednesday, July 01, 2009 2:50 PM
Graham Percival wrote:
I intend on really testing my claim that a FAQ merely
demonstrates problems in the docs. I intend on having very good
docs (including the website as "docs"), so that means the FAQ
should be minimal.
Why not view the FAQ as part of the docs? Nobody will read the
full documentation from the first to the last page, and remember
every single fact that's included. Also, different people use very
different strategies when searching for information. A good FAQ
should provide short answers and link to the full manuals for more
information.
To mention one example of a FAQ, I just answered an email that
asked why the score line wasn't broken so that the music continued
after the end of the page. Currently, the answer to this question
is very hard to find in the docs even if you know the answer (very
likely a typo in the duration of some note). The only place I
could find in the LM is the recommendation to use bar checks in
"5.1.1 General suggestions" (but it doesn't mention the symptom).
In the NR, the only explicit mentioning of the problem I could
find was in "1.2.5 Bars" and some related information can be found
in "4.3.1 Line breaking".
However, my main point here is not to rant about the deficiencies
of the current docs (since then I would have spent my time much
better by rewriting the docs instead of writing this email), but
the problem is that even if we add a warning in the LM similar to
the one in NR 1.2.5, most users will not remember it from the
first time they read the LM, no matter how many bells an whistles,
since they don't realize exactly what the problem is until they
have experienced it themselves for the first time. Once the user
first encounters this problem himself in his own typesetting work,
the LM is still far too long to browse through and it's not
immediately obvious that the problem is related to bar lines so
that you should look in NR 1.2.5. However, if there's a good FAQ
with, say, 10 - 20 entries at most, then it's easy for the user to
browse it through and quickly find the relevant answer.
As I said, the way you search for information differs from person
to person and from situation to situation, so we need to provide
lots if different entry points to help people find the relevant
information. An FAQ is a very good form for one of these entry
points. This will necessarily require some duplication of
information (which at least in the early stages of the GDP was a
no-no), but since the FAQ should not provide the details but
rather point to the other documentation for the long answers, it
will not be a large maintenance burden. Other important entry
points are the Indexes (are they still separate for the different
documents) and the LSR, for example.
/Mats
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
