Thread: the sad state of our FAQs
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
On Sat, Mar 7, 2009 at 6:05 AM, Stefan Kaltenbrunner <stefan@kaltenbrunner.cc> wrote:
+1
And please send people directly to the wiki FAQs from menu links, and redirect from existing pages.
-selena
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
And please send people directly to the wiki FAQs from menu links, and redirect from existing pages.
-selena
--
Selena Deckelmann
Open Source Bridge - http://www.opensourcebridge.org
PDXPUG - http://pugs.postgresql.org/pdx
Me - http://www.chesnok.com/daily
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
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. [...] > 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. I completely agree that having a bad translation is worse than not having a translation at all. However, enthusiastic people will translate anything you throw at them, and if the tools don't help, the results will be less than ideal; bad formatting, slightly wrong answers, outdated answers. If we move the FAQ to the wiki, the outdated translations will not disappear nor be automatically updated. I claim that if we move them to a translatable framework that helps people notice when the translation is nonexistant or out of date, we will have better results. I proposed this previously but got no support from Bruce who is supposed to be the FAQ maintainer, and thus I ended up doing nothing. Therefore I now offer to do the job required to move them to XML Docbook and allow translatability using xml2po or something similar. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Alvaro Herrera <alvherre@commandprompt.com> writes:
> If we move the FAQ to the wiki, the outdated translations will not
> disappear nor be automatically updated. I claim that if we move them to
> a translatable framework that helps people notice when the translation
> is nonexistant or out of date, we will have better results.
> I proposed this previously but got no support from Bruce who is supposed
> to be the FAQ maintainer, and thus I ended up doing nothing. Therefore
> I now offer to do the job required to move them to XML Docbook and allow
> translatability using xml2po or something similar.
ISTM there are two separate issues here. One is whether we want to get
the FAQs out of CVS and into some more widely-editable place. The other
is whether to adopt some tools/framework to ease maintenance of
translated versions. I'm in favor of both (though am not personally
prepared to expend any work for it :-(). I do not know whether xml2po
is the most suitable tool, though.
The one good thing that having the FAQs in CVS does for us is make it
fairly easy to have version-specific FAQs. I don't think we've really
exploited that capability, except in the indirect sense that we simply
stopped updating back branches' FAQs (which hardly seems ideal). So
losing it doesn't seem like a showstopper objection to me. Still, it's
something that might be nice to preserve if we can.
regards, tom lane
On Sun, Mar 8, 2009 at 9:04 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > The one good thing that having the FAQs in CVS does for us is make it > fairly easy to have version-specific FAQs. I don't think we've really > exploited that capability, except in the indirect sense that we simply > stopped updating back branches' FAQs (which hardly seems ideal). So > losing it doesn't seem like a showstopper objection to me. Still, it's > something that might be nice to preserve if we can. > There's nothing stopping us from maintaining per-version FAQs in a wiki environment. We just put up a page for "FAQ 7.4", "FAQ 8.0" and so on, with "FAQ" always redirecting to the page for the latest stable release. Although to be frank I think the value of per-version FAQs is dubious.I would be totally okay with seeing the back-branchFAQs 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. Cheers, BJ
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.
regards, tom lane
On Mar 7, 2009, at 2:33 PM, Tom Lane <tgl@sss.pgh.pa.us> 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). > > 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. Another approach would be to tag each FAQ with what version it was created for and what version it is deprecated for. (pretty much what Brenden suggested, but slightly less overhead than listing all versions the FAQ applies to) Then we could do cool things like generate the version specific FAQs programmatically and not ever worry about removing them. -Selena
Magnus Hagander a écrit : > Stefan Kaltenbrunner wrote: >>[...] >> 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. > +1 too. > 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". > I did the translation with a few other guys a long time ago. I wanted to maintain it, but it was a lot more work than I could spend on it. I don't think this has changed. I think the best thing to do is to get rid of it right now (it being the french translation). -- Guillaume. http://www.postgresqlfr.org http://dalibo.com
Selena Deckelmann wrote: > On Mar 7, 2009, at 2:33 PM, Tom Lane <tgl@sss.pgh.pa.us> 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). >> >> 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. > > Another approach would be to tag each FAQ with what version it was > created for and what version it is deprecated for. (pretty much what > Brenden suggested, but slightly less overhead than listing all versions > the FAQ applies to) > > Then we could do cool things like generate the version specific FAQs > programmatically and not ever worry about removing them. Yeah so some simple tags/icons like "8.1+, 7.4 only, 8.0 and older" on a per entry base? We also could use something like an "outdated" template for flagging specific entries or complete FAQ/wiki pages. I don't really think that the per version FAQ is really a reality - we only have one version on the main website (which is actually -HEAD I think which makes it even more weird) and I really doubt that a lot of people are reading them elsewhere. Stefan
> 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. If you are suggesting that you remove well-maintained localized FAQs together, then I against it. We should remove unmaintained localized FAQs first IMO. The discussion about English FAQ's state is completely another story, though. -- Tatsuo Ishii SRA OSS, Inc. Japan
Tatsuo Ishii wrote: >> 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. > > If you are suggesting that you remove well-maintained localized FAQs > together, then I against it. We should remove unmaintained localized > FAQs first IMO. I was just suggesting moving all of them them and only link to those that are reasonably well maintained. So for a well maintained faq like the japanese one the only thing that would change is that you can translate it directly in the wiki instead of sending a patch to bruce. > > The discussion about English FAQ's state is completely another story, > though. well it's clearly related because there is a direct relation between the source (the english one) and the translations. Stefan
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
> > If you are suggesting that you remove well-maintained localized FAQs > > together, then I against it. We should remove unmaintained localized > > FAQs first IMO. > > I was just suggesting moving all of them them and only link to those > that are reasonably well maintained. > So for a well maintained faq like the japanese one the only thing that > would change is that you can translate it directly in the wiki instead > of sending a patch to bruce. I don't know if Japanese FAQ maintainer would gladly do the reformatting work to upload to Wiki. Does anyone have a script to translate from HTML to Wiki? -- Tatsuo Ishii SRA OSS, Inc. Japan
> > If you are suggesting that you remove well-maintained localized FAQs > > together, then I against it. We should remove unmaintained localized > > FAQs first IMO. > > I was just suggesting moving all of them them and only link to those > that are reasonably well maintained. > So for a well maintained faq like the japanese one the only thing that > would change is that you can translate it directly in the wiki instead > of sending a patch to bruce. I don't know if Japanese FAQ maintainer would gladly do the reformatting work to upload to Wiki. Does anyone have a script to translate from HTML to Wiki? -- Tatsuo Ishii SRA OSS, Inc. Japan
Tatsuo Ishii wrote: > > I was just suggesting moving all of them them and only link to those > > that are reasonably well maintained. > > So for a well maintained faq like the japanese one the only thing that > > would change is that you can translate it directly in the wiki instead > > of sending a patch to bruce. > > I don't know if Japanese FAQ maintainer would gladly do the > reformatting work to upload to Wiki. Does anyone have a script to > translate from HTML to Wiki? What do you (and the Japanese FAQ maintainer) think of the idea of managing the translation with PO tools instead? -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.
Tatsuo Ishii wrote: >>> If you are suggesting that you remove well-maintained localized FAQs >>> together, then I against it. We should remove unmaintained localized >>> FAQs first IMO. >> I was just suggesting moving all of them them and only link to those >> that are reasonably well maintained. >> So for a well maintained faq like the japanese one the only thing that >> would change is that you can translate it directly in the wiki instead >> of sending a patch to bruce. > > I don't know if Japanese FAQ maintainer would gladly do the > reformatting work to upload to Wiki. Does anyone have a script to > translate from HTML to Wiki? IIRC I did a test-translation of the FAQ from the *text* format we have in CVS today to the wiki, and it was trivial. He'll definitely want to use that as base and not the HTML. //Magnus
On Sun, Mar 8, 2009 at 9:33 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > 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 agree, and note that at least one of the existing FAQs already adopts this style of advice. In 4.19: "In PostgreSQL versions < 8.3, ... This problem does not occur in PostgreSQL 8.3 and later." While I'm not a big fan of using comparison operators in English prose, this approach seems to work well. > > I guess the sticking point would be about how long to preserve FAQ > entries that are no longer relevant to the current release. > Really something to be worked out on a per-case basis I suppose. If the goal of the FAQ is to help people who have Questions that are Asked Frequently, then we could stop mentioning a release when people stop asking questions about it? Cheers, BJ
Alvaro Herrera wrote: > I proposed this previously but got no support from Bruce who is supposed > to be the FAQ maintainer, and thus I ended up doing nothing. Therefore > I now offer to do the job required to move them to XML Docbook and allow > translatability using xml2po or something similar. I am fine with whatever changes people suggestion; the FAQ just isn't updated that often for me to care where it resides. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian wrote: > Alvaro Herrera wrote: >> I proposed this previously but got no support from Bruce who is supposed >> to be the FAQ maintainer, and thus I ended up doing nothing. Therefore >> I now offer to do the job required to move them to XML Docbook and allow >> translatability using xml2po or something similar. > > I am fine with whatever changes people suggestion; the FAQ just isn't > updated that often for me to care where it resides. I think that statement alone is a good indicator of why it has to be moved. Some figures for the interested, btw. The FAQ had ~7700 reads from ~6300 unique visitors last month. These people received information that was simply incorrect. I think that's more than enough people to care about. As a reference point, the Windows FAQ on the wiki had ~6900 reads from ~5800 unique visitors (the most popular page on the wiki other than the frontpage). So I think it's pretty clear that putting it on the wiki doesn't make less people look at it - at least not with the link that's there from the main site. //Magnus
On Sat, 2009-03-07 at 16:53 -0300, Alvaro Herrera wrote: > I proposed this previously but got no support from Bruce who is supposed > to be the FAQ maintainer, and thus I ended up doing nothing. Therefore > I now offer to do the job required to move them to XML Docbook and allow > translatability using xml2po or something similar. I would like to see us have a single documentation standard though. Our core docs are still Docbook SGML which is a bit different :( Other than that, I am all for it. Joshua D. Drake > > -- > Alvaro Herrera http://www.CommandPrompt.com/ > PostgreSQL Replication, Consulting, Custom Development, 24x7 support > -- PostgreSQL - XMPP: jdrake@jabber.postgresql.org Consulting, Development, Support, Training 503-667-4564 - http://www.commandprompt.com/ The PostgreSQL Company, serving since 1997
Joshua D. Drake wrote: > On Sat, 2009-03-07 at 16:53 -0300, Alvaro Herrera wrote: > > > I proposed this previously but got no support from Bruce who is supposed > > to be the FAQ maintainer, and thus I ended up doing nothing. Therefore > > I now offer to do the job required to move them to XML Docbook and allow > > translatability using xml2po or something similar. > > I would like to see us have a single documentation standard though. Our > core docs are still Docbook SGML which is a bit different :( Other than > that, I am all for it. Magnus has extor^Wconvinced me over IM to drop this idea, which means less work for me. Yay! -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
> Bruce Momjian wrote: > > Alvaro Herrera wrote: > >> I proposed this previously but got no support from Bruce who is supposed > >> to be the FAQ maintainer, and thus I ended up doing nothing. Therefore > >> I now offer to do the job required to move them to XML Docbook and allow > >> translatability using xml2po or something similar. > > > > I am fine with whatever changes people suggestion; the FAQ just isn't > > updated that often for me to care where it resides. > > I think that statement alone is a good indicator of why it has to be moved. > > Some figures for the interested, btw. > > The FAQ had ~7700 reads from ~6300 unique visitors last month. > > These people received information that was simply incorrect. I think > that's more than enough people to care about. > > > As a reference point, the Windows FAQ on the wiki had ~6900 reads from > ~5800 unique visitors (the most popular page on the wiki other than the > frontpage). So I think it's pretty clear that putting it on the wiki > doesn't make less people look at it - at least not with the link that's > there from the main site. I am suprised to see this number is so *small*. I guess the number of PostgreSQL users on Windows are 10 times larger than any other platforms at least. So if your theory is correct, I think Windows FAQ accesses should be 10 times larger. -- Tatsuo Ishii SRA OSS, Inc. Japan
Joshua D. Drake wrote: > On Sat, 2009-03-07 at 16:53 -0300, Alvaro Herrera wrote: > >> I proposed this previously but got no support from Bruce who is supposed >> to be the FAQ maintainer, and thus I ended up doing nothing. Therefore >> I now offer to do the job required to move them to XML Docbook and allow >> translatability using xml2po or something similar. > > I would like to see us have a single documentation standard though. Our > core docs are still Docbook SGML which is a bit different :( Other than > that, I am all for it. I think, although others might disagree, that the FAQ is by its nature more of a web resource than a software documentation resource. So it ought to be managed by the standards of the web site, e.g., rapid releases, version independent, whatever translation system the web site uses. (I consider the wiki to be an extension of the web site, for this argument.)
Bruce Momjian wrote: > Alvaro Herrera wrote: >> I proposed this previously but got no support from Bruce who is supposed >> to be the FAQ maintainer, and thus I ended up doing nothing. Therefore >> I now offer to do the job required to move them to XML Docbook and allow >> translatability using xml2po or something similar. > > I am fine with whatever changes people suggestion; the FAQ just isn't > updated that often for me to care where it resides. With some help from alvaro I just moved the current version of the FAQ to http://wiki.postgresql.org/wiki/FAQ. For now this is mostly just a reformatted version of what is on the main site with some minor adjustments done (like spelling fixes and some invalid URLs removed). I will look into updating the website if people think this version is fine. Stefan
Stefan Kaltenbrunner wrote: > With some help from alvaro I just moved the current version of the FAQ > to http://wiki.postgresql.org/wiki/FAQ. For now this is mostly just a > reformatted version of what is on the main site with some minor > adjustments done (like spelling fixes and some invalid URLs removed). > > I will look into updating the website if people think this version is fine. There are some very minor formatting glitches left, but the good thing about this being on the wiki is that anybody can go and fix them. The bad thing is that translations have to be maintained by hand (as they always have). The spanish one is already in place: http://wiki.postgresql.org/wiki/Preguntas_Frecuentes Stefan tells me that Mediawiki has plugins to help with the translation, but for now they continue to require hand inspection. We'll welcome more information on this regard. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Stefan Kaltenbrunner escribió: > 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). Okay, so the FAQ is now on the Wiki. Is anybody actually going to work on overhauling it? I'm also wondering why do we have two pages, FAQ and Frequently_Asked_Questions. Shouldn't they be merged? -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
On Tue, 17 Mar 2009, Alvaro Herrera wrote: > I'm also wondering why do we have two pages, FAQ and > Frequently_Asked_Questions. Shouldn't they be merged? I started putting stuff on that other page while I waited for the official FAQ to get migrated over. There are a fair number of wiki pages tagged in the FAQ category as well. Some of those are too big to really merge usefully into the FAQ, others might get dumped into the main document. Several of the pages listed on there were aimed to replace or supplement existing entries in the full FAQ from the start. As an example, "4.2 How do I control connections from other hosts?" has considerably less information than any newbie needs to resolve those problems, as anybody hanging out on IRC is painfully aware. I wrote an initial draft of something on the "Client Authentication" page on the Wiki to help pull together pointers to all the relevant places in the documentation, into something closer to a walkthrough, and the result is larger than FAQ-entry length. That's going to stay a FAQ *page* instead, I think, one that gets pointed to as a supplemental reference for the terse description given for 4.2 right now. I can help sort through all this once I get past my next conference gig in another week, all my spare time has been spent tormenting systems with pgbench lately. -- * Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD
Greg Smith escribió: > That's going to stay a FAQ *page* instead, I think, one that gets > pointed to as a supplemental reference for the terse description given > for 4.2 right now. Sure, that makes a lot of sense. -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.