Re: Updating FAQs

[Yoshinori K. Okuji]

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