Re: new website: draft 3

[Graham Percival]

On Wed, Jul 01, 2009 at 03:50:14PM +0200, Mats Bengtsson wrote:
>
> Graham Percival wrote:
>> I intend on really testing my claim that a FAQ merely
>> demonstrates problems in the docs.

> Why not view the FAQ as part of the docs?

Where do we draw the line for F?  I mean, "how do I make
artificial harmonics" was common question for string players.
"how does \relative work" used to be an extremely common question.
If we include links to every question to the docs, then the FAQ
will be almost as long as the docs themselves.

Now, note that the above questions *used* to be frequently asked,
but they're not any more.  We still get lots of questions about
vocal music, spacing, scheme tweaks, and the lack of a GUI.  What
do all those questions have in common?  They're all items that we
haven't seriously improved in the docs.

(the "where is the GUI" question is being addressed in the website
rewrite, of course)

> Also, different people use very different  strategies when
> searching for information.

Yes; we have the TOC approach (mine), the index (others), and once
I get around to it merging it, the actual search box (from
Reinhold).

> 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.

To my mind, this is a perfect example of what should *not* go in
the FAQ.  Rather, we should improve LM 5.1 or .2, which Trevor has
started.  (I've been asking about completing the LM for slightly
longer than a year)

> However, my main point here is not to rant about the deficiencies of the  
> current docs

It should be, though.

> Once the user first encounters this problem himself in his own  
> typesetting work, the LM is still far too long to browse through

Agreed!  That's why it goes in "when things go wrong".


As I said before, this is an experiment.  I have a hypothesis: we
can reduce (to zero) the frequency of asked questions by improving
the documentation.  How will I test this hypothesis?  I will
observe the frequency of questions.

When I notice a question being frequent, I will modify the docs.
After X months, I will compare the frequency of that question to
the frequency of that question before the modification.  If the
frequency doesn't go down, then I'll either modify the docs some
more, or add it as a FAQ.

ok, I admit it's not a "hard science" experiment.  I haven't
defined the "X months", I left wiggle room in my "... modify the
docs some more", etc.


But in all serious -- and not trying to brag[1] -- for the past
five years, I've never touched the FAQ, but we *have* seen a
reduction in questions about the parts of the docs I've worked on
(either directly or indirectly).  "how does \relative work" is a
question I remember with extreme un-fondness from the early 00's.
"where do I put the command" was common two years ago; not common
now.  "where is the gui" is unfortunately still common, but the
new website and the 10.5 GUI work should fix that.

[1]  I think that anybody could get similar results, if they spent
the same amount of time as I've spent on the lilypond docs.

Cheers,
- Graham