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 _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
