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
