lilypond-user
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: new website: draft 3


From: Mats Bengtsson
Subject: Re: new website: draft 3
Date: Thu, 02 Jul 2009 13:59:01 +0200
User-agent: Thunderbird 2.0.0.5 (X11/20070716)



Graham Percival wrote:
On Thu, Jul 02, 2009 at 10:22:11AM +0200, Mats Bengtsson wrote:
Do you mean into the current LM 5.2 "When thing's don't work" or somewhere else? If you prefer to rename the FAQ (or rather the section on common mistakes of the FAQ) into "When things go wrong", I'd claim that it's still a FAQ.

My understanding of a FAQ is that it would include any frequently
asked question.
Right, but many FAQ lists are order into subcategories
 So things like like "how does \relative work?" or
"does it run on windows?" would qualify, if those were being
asked.

My understanding of "LM 5.2 When things don't work" is that it
would include tips on finding and fixing problems in lilypond
files: add bar lines, try commenting out sections, and recognizing
odd error messages.
yes, this would be one subtitle within a well-organized FAQ.
These two things are not the same.
Right, one is a subset of the other.

We haven't had a (real) FAQ for years.  Another six months won't
hurt.
Agreed! However, I don't think it's a good idea to hide something that most people would expect to find in a good FAQ, as a level 2 section in the learning manual. My proposal is simply to include a "FAQ" link which is easily found on the web page and let it contain a link to the "When things don't work" as well as to the Tutorial (or whatever is suited for the "where's the application" type questions and possibly some more place. Remember that one of the most difficult things of good pedagogy is to provide the information that the learner considers relevant for the moment. Even if you as a teacher/senior/document writer/whatever know that some piece of information is very important, the learner/student/user/... will not digest it unless he is in a situation where he finds it important. Compare to when you attend a guided tour at a museum and the first thing the guide is telling you is that the toilet is located on the third floor to the left. Since you don't have any urgent need for that information at that moment, you will forget it, and one hour later when you urgently need the information, the guide has left to take care of the next group of tourists. Based on your previous experience with museums, you will probably go to the entrance hall, where you hopefully can find the sign to the toilet.

Similarly, when you are reading the LM the first time, you have hopefully not experienced the problem of notes running out of the paper and since there are so many other new things to digest, so even if you notice that there's a section called "When thing's don't work", you will probably not remember exactly where you saw it, once you need it. Based on your previous experience of other software, you know that there often is a FAQ, which might be able to provide an answer. So, you go to the lilypond web and since there's no FAQ at the main page, you click on Manuals; still no FAQ (assuming that Graham has removed it by then) and try desperately to figure out which of all the links might provide something useful. Since your LilyPond:ing already started to take off, it's not obvious to look into the LM. Since very few other pieces of software, have their documentation divided into "Learning Manual", "Notation Reference" and "Application Usage", it may be even less obvious where to look. The division into "Introduction" and "Regular use" is great and provides useful extra hints on where to look, as long as nobody feels offended that he has to look under "Introduction" after 2 years of LilyPonding.

Don't be offended, Graham! I really like the effort you have put into the docs and the organization of the docs, but sometimes it's like you have been hit by the"not invented here" syndrome. What's wrong with having a link called "FAQ" that provides yet another entry point into the existing manuals, for people looking for information?

    /Mats





reply via email to

[Prev in Thread] Current Thread [Next in Thread]