public inbox for [email protected]  

help / color / mirror / Atom feed

From: Stefan Kaltenbrunner <[email protected]>
To: Tom Lane <[email protected]>
Cc: Brendan Jurd <[email protected]>
Cc: Alvaro Herrera <[email protected]>
Cc: PostgreSQL www <[email protected]>
Cc: [email protected]
Subject: Re: [DOCS] the sad state of our FAQs
Date: Sun, 08 Mar 2009 09:53:53 +0100
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>
	<[email protected]>

Tom Lane wrote:
> Brendan Jurd <[email protected]> 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

view thread (29+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected], [email protected]
  Subject: Re: [DOCS] the sad state of our FAQs
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox