the sad state of our FAQs
От | Stefan Kaltenbrunner |
---|---|
Тема | the sad state of our FAQs |
Дата | |
Msg-id | 49B27F0E.2050504@kaltenbrunner.cc обсуждение исходный текст |
Ответы |
Re: the sad state of our FAQs
Re: the sad state of our FAQs Re: the sad state of our FAQs Re: the sad state of our FAQs |
Список | 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 themaximum 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 withoutan actual link -> 4.12 should talk about the deprecation status of OIDs at least -> 4.13 seems like a fairly unhelpfuland 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 thoseon 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
В списке pgsql-www по дате отправления: