Re: [DOCS] the sad state of our FAQs

Tom Lane wrote:
> Brendan Jurd <direvus(at)gmail(dot)com> writes:
>> Although to be frank I think the value of per-version FAQs is dubious.
>> I would be totally okay with seeing the back-branch FAQs abandoned in
>> favour of the One FAQ (to rule them all, etc).
>
>> Perhaps, instead of back-branch FAQs which are bound to be mostly an
>> old copy of the One FAQ, we could have some kind of "Things to Note If
>> You're Running an Older Version" article.
>
> In the past, Bruce has not hesitated to rip out or replace FAQ entries
> as soon as they became obsolete. That approach would have to change if
> we went to a one-true-FAQ approach. In particular, it's often the case
> that the best way to do something depends on which version you're
> running.
>
> I think it might well be true though that it'd be better to have one FAQ
> with answers that say something like "Before version x.y, do this ...
> in x.y and later, do that ...". That approach makes sure that people
> know that they are reading version-specific advice; whereas the separate
> FAQs approach makes it pretty easy for people to fail to notice that
> they are reading advice that's inappropriate for their version.
>
> I guess the sticking point would be about how long to preserve FAQ
> entries that are no longer relevant to the current release.

Well a more extreme thing would to to ask "What is the purpose of our FAQ?".
In the current state it imho contains a few actual FAQ worth things
(mostly stuff in the "General" section) the rest seems to be incomplete
duplication of information that is already available in a better form
elsewhere (be it the wiki, the main docs, the IRC docbot or external
resources).
So maybe the current FAQ needs an overhaul in the sense of reducing it
to a much smaller number of things in the main FAQ and replacing the
rest of the things with something that provides much easier access to
the available resources(which I frankly think the search and the wiki
already does so people are not actually reading the FAQs any more).

Whatever that "something" could be it seems it would reduce our
maintainance overhead as well as improve the accuracy if we keep
information in one place and not try to duplicate in multiple sources.

Stefan