[Top][All Lists]
[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
- Re: new website: draft 3, (continued)
- Re: new website: draft 3, Graham Percival, 2009/07/02
- Re: new website: draft 3, Werner LEMBERG, 2009/07/02
- Re: new website: draft 3, Graham Percival, 2009/07/02
- Re: new website: draft 3, Werner LEMBERG, 2009/07/02
- Re: new website: draft 3, Graham Percival, 2009/07/02
- Re: new website: draft 3, Patrick Horgan, 2009/07/02
Re: new website: draft 3, Graham Percival, 2009/07/02
- Re: new website: draft 3, Mats Bengtsson, 2009/07/02
- Re: new website: draft 3, Graham Percival, 2009/07/02
- Re: new website: draft 3, Trevor Daniels, 2009/07/02
- Re: new website: draft 3,
Mats Bengtsson <=
- Re: new website: draft 3, Graham Percival, 2009/07/03
- Re: new website: draft 3, James E. Bailey, 2009/07/03
- Re: new website: draft 3, Francisco Vila, 2009/07/03
- Re: new website: draft 3, David Stocker, 2009/07/03
- Re: new website: draft 3, Anthony W. Youngman, 2009/07/07
Re: new website: draft 3, Carl D. Sorensen, 2009/07/02