Message-ID: <49B387A1.7090708@kaltenbrunner.cc>
Date: Sun, 08 Mar 2009 09:53:53 +0100
From: Stefan Kaltenbrunner <stefan@kaltenbrunner.cc>
User-Agent: Mozilla-Thunderbird 2.0.0.19 (X11/20090103)
MIME-Version: 1.0
To: Tom Lane <tgl@sss.pgh.pa.us>
CC: Brendan Jurd <direvus@gmail.com>,
	Alvaro Herrera <alvherre@commandprompt.com>,
	PostgreSQL www <pgsql-www@postgresql.org>, pgsql-docs@postgresql.org
Subject: Re: [DOCS] the sad state of our FAQs
References: <49B27F0E.2050504@kaltenbrunner.cc>
	<20090307195305.GB3821@alvh.no-ip.org>
	<18162.1236463457@sss.pgh.pa.us>
	<37ed240d0903071418u541851f8pac6cb16fe48e859d@mail.gmail.com>
	<18473.1236465193@sss.pgh.pa.us>
In-Reply-To: <18473.1236465193@sss.pgh.pa.us>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Tom Lane wrote:
> Brendan Jurd <direvus@gmail.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