[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Updating FAQs
From: |
Yoshinori K. Okuji |
Subject: |
Re: Updating FAQs |
Date: |
Wed, 26 Nov 2003 21:37:56 +0100 |
User-agent: |
KMail/1.5 |
Instead of pointing out what questions should be included, I'd like to
suggest the general direction.
In principle, FAQ is prepared to reduce the burden of developers. It is
also useful for ordinary users, but the main purpose is make lives of
developers easier. So a good FAQ should decrease the number of mails
sent to us.
Readability is the most important to make a good FAQ, I think. Even if
you make a complete list of questions and answers, if nobody reads it,
it is useless.
The current FAQ is bad, not only because it is not up-to-date, but also
because it is not well-written. It was good when it had a few
questions. Now it has many questions and mostly unrelevant to most
users. Bad. Normally, if a documentation looks long, people avoid
reading it.
The direction would be 1) not to increase the number of questions too
much and 2) to make the structure better if necessary. If you can cover
99% of questions by less than 10 entries, that's great. You don't need
to care about how to organize the FAQ. If you need more than 20, please
consider separating questions into sections.
Okuji