the sad state of our FAQs

From: Stefan Kaltenbrunner <stefan(at)kaltenbrunner(dot)cc>
To: PostgreSQL www <pgsql-www(at)postgresql(dot)org>
Cc: pgsql-docs(at)postgresql(dot)org
Subject: the sad state of our FAQs
Date: 2009-03-07 14:05:02
Message-ID: 49B27F0E.2050504@kaltenbrunner.cc
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs pgsql-www

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
* 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.

Stefan

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Selena Deckelmann 2009-03-07 14:07:48 Re: the sad state of our FAQs
Previous Message Thom Brown 2009-02-18 16:27:49 Doc enhancements

Browse pgsql-www by date

  From Date Subject
Next Message Selena Deckelmann 2009-03-07 14:07:48 Re: the sad state of our FAQs
Previous Message Josh Berkus 2009-03-06 23:55:46 Pentabarf instance for pgDays?