Re: the sad state of our FAQs

Stefan Kaltenbrunner wrote:
> Our FAQs are in a really sad state and it#s about time to think about
> what we want to do about that because in the current state there are
> creating much more harm than good.
>
> Just from a quick glance we have:
>
> German FAQ - last updated at the end of 2007, talks about 8.2.5 as the
> current release, contains a ton of factual errors on outdated
> information and urls
>
> French FAQ - last updated in 2004, has broken encoding (so it seems
> pretty clear it is not used much at all), thinks 7.4.5 is our current
> release and
>
> Hungarian FAQ - last updated in 2005
>
> Some of the others also look outdated and seem to contain outdated
> informations.
>
> Even the main FAQ seems to be in need of an overhaul - random
> oberservations include:
>
> * current release is 8.3.3

It has been mentioned several times before that this shouldn't be in the
FAQ - it should just refer to the website as the listing of the current
version.

(not going to comment on all the other points individually, just the
comment at the bottom)

> * a fairly large number of URLs are outdated, invalid or are not
> pointing directly to the current autoritative sources (TODO,Developer
> FAQ, varlena.com links, ...)
> * some articles are either fairly pointless, duplicate the main docs or
> need to at least get fleshed out a bit:
>
> -> 3.1 seems rather short on actual content, duplicates (better)
> information in the main docs as well as in the wiki and does not talk
> about what likely is 95% of our installed based (ie packages)
> -> 3.5 is slightly wrong as in we are trying to determine the maximum
> at initdb time up to the stated limit of 100 (also some packages have
> different defaults)
> -> 4.2 not sure it is sensible to refer to a C-source file instead of
> the docs here for the average user
> -> 4.5 has a spelling error s/avergages/averages
> -> 4.7 not a very useful reference without an actual link
> -> 4.12 should talk about the deprecation status of OIDs at least
> -> 4.13 seems like a fairly unhelpful and maybe wrong general advise (a
> datasize limit of 256MB would be considered a joke for a lot of usecases
> and is likely much smaller that what the default in a modern OS is)
> without some more discussion
> -> 4.20 duplicates the main docs as well as some wiki stuff in a bad way
>
> this is just from a 10min read of the FAQ so I guess there are more
> things that are worth discussing like with the platform specific FAQs
> which seem to be in a similiar bad shape).
>
> To sum the current state up:
>
> * have have a number of the localized FAQs in a very outdated and wrong
> state
> * the main FAQ contains a lot of duplication of stuff documented and
> discussed better in other places as well as missing a lot of thinge to
> make them better usable (like instead of "look in the manual for
> EXPLAIN" or "See the create_sequence manual page" why not provide an
> actual URL/link to those)
> * we have a number of invalid/wrong URLs in there
> * appearently most FAQ maintainers lost interest in keep up with the
> translations which I guess is a result of the ridiculous way to keep
> them updated right now (provide a source level patch, send it to bruce
> and wait for it getting commited)
> * a lot of things that ARE actually asked a lot are not mentioned in the
> FAQ at all
>
> My proposal is to move all the FAQs to the wiki(just with what happened
> with the developer FAQ) with the hope that more people get interested in
> keeping them up to date and only reference those on the main page that
> at least contains "somewhat" accurate information.I honestly believe
> that the current state is more damaging that not having any (translated
> FAQs) at all.

+1. Or rather, +8743 or something, if I get that many votes for some reason.

The developer faq shows a fairly healthy set of different authors, so I
think we can fairly say that moving that one really helped.

Then we can always ask the local groups like postgresqlfr if they
actualliy want to keep the FAQ on the main site at all or link to a FAQ
they have on their local site... My bet is that information on that site
is another reason why they haven't been bothering with the "main FAQ".

//Magnus