TODO, FAQs to Wiki?

Bruce Momjian wrote:

I am impressed at the state of the May wiki patch queue:

http://wiki.postgresql.org/wiki/CommitFest:May

It is even tracking the psql wrap patch I am working on now.

Thanks. We've put a certain amount of effort on it. Credit for the
templating system goes to Brendan Jurd, who implemented the way to make
it display as tables but without the messy markup. I think the
templates that are now in place make for a reasonably comfortable
environment. Not as simple as editing a plain text file, but I expect
it is lean enough.

Magnus has started moving the Developer's FAQ to a wiki. I am thinking
we should move the main FAQ and the TODO list to a wiki as well if the
community is in agreement.

Having the TODO on the wiki makes plenty of sense IMHO. Magnus showed
me an experiment some time ago and it looked good (modulo some errors in
the conversion, but I think that's to be expected.)

The FAQs are another matter however. I suggested some time back moving
those to DocBook XML. A friend was working on a script to do the
initial conversion automatically. The nice thing about it is that we
can then use the xml2po tools to create PO files for translation. This
means that translations are more easily kept up to date. Are you open
to this possibility?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:

Bruce Momjian wrote:

I am impressed at the state of the May wiki patch queue:

http://wiki.postgresql.org/wiki/CommitFest:May

It is even tracking the psql wrap patch I am working on now.

Thanks. We've put a certain amount of effort on it. Credit for the
templating system goes to Brendan Jurd, who implemented the way to make
it display as tables but without the messy markup. I think the
templates that are now in place make for a reasonably comfortable
environment. Not as simple as editing a plain text file, but I expect
it is lean enough.

Yes, I was surprised at the sophistication of the layout.

Magnus has started moving the Developer's FAQ to a wiki. I am thinking
we should move the main FAQ and the TODO list to a wiki as well if the
community is in agreement.

Having the TODO on the wiki makes plenty of sense IMHO. Magnus showed
me an experiment some time ago and it looked good (modulo some errors in
the conversion, but I think that's to be expected.)

Yes, he showed me too. I was worried no one but me would update it but
at this point I think others will get involved.

The FAQs are another matter however. I suggested some time back moving
those to DocBook XML. A friend was working on a script to do the
initial conversion automatically. The nice thing about it is that we
can then use the xml2po tools to create PO files for translation. This
means that translations are more easily kept up to date. Are you open
to this possibility?

Yes. The FAQ's change very infrequently, and XML would be fine for
those, especially since it would lessen the translation load.

--
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:

The FAQs are another matter however. I suggested some time back moving
those to DocBook XML. A friend was working on a script to do the
initial conversion automatically. The nice thing about it is that we
can then use the xml2po tools to create PO files for translation. This
means that translations are more easily kept up to date. Are you open
to this possibility?

Yes. The FAQ's change very infrequently, and XML would be fine for
those, especially since it would lessen the translation load.

It seems that this should be a -docs discussion, no? Also although I am
in favor of XML, I think it makes more sense to have it in the native
documentation format, which is not XML but SGML.

Now if we want to move the main docs to XML as well I am a loud +1. Yes
I am aware we can do make xml.

Sincerely,

Joshua D. Drake

Hello

Magnus has started moving the Developer's FAQ to a wiki. I am thinking
we should move the main FAQ and the TODO list to a wiki as well if the
community is in agreement.

Czech translation of FAQ is on wiki one year - and it's much more
maintainable than HTML.
http://www.pgsql.cz/index.php/Frequently_Asked_Questions

I am using FAQ support for mediawiki
http://www.mediawiki.org/wiki/Extension:NiceCategoryList

Regards
Pavel Stehule

Alvaro Herrera wrote:

The FAQs are another matter however. I suggested some time back
moving those to DocBook XML. A friend was working on a script to do
the initial conversion automatically. The nice thing about it is
that we can then use the xml2po tools to create PO files for
translation. This means that translations are more easily kept up to
date. Are you open to this possibility?

What would be the advantage of keeping it in DocBook over the wiki? One
of the main advantages of keeping it on the wiki would be to allow
others to help out with the editing of them.

Looking at the state of many of our non-english FAQs today, I don't put
too much faith into a system that'll just show people "this is not
translated". I think it's more likely to get better if the people can
just edit the translations directly instead of having to produce a
patch (and to make that work, they have to set up a build system for
processing docbook which is certainly far from trivial on some
platforms), etc...

//Magnus

Magnus Hagander wrote:

Looking at the state of many of our non-english FAQs today, I don't put
too much faith into a system that'll just show people "this is not
translated". I think it's more likely to get better if the people can
just edit the translations directly instead of having to produce a
patch (and to make that work, they have to set up a build system for
processing docbook which is certainly far from trivial on some
platforms), etc...

There are web platforms for editing POs.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Magnus Hagander wrote:

Alvaro Herrera wrote:

The FAQs are another matter however. I suggested some time back
moving those to DocBook XML. A friend was working on a script to do
the initial conversion automatically. The nice thing about it is
that we can then use the xml2po tools to create PO files for
translation. This means that translations are more easily kept up to
date. Are you open to this possibility?

What would be the advantage of keeping it in DocBook over the wiki? One
of the main advantages of keeping it on the wiki would be to allow
others to help out with the editing of them.

Two words:

print format

If we want to push the FAQ to the wiki, we should write a stylesheet
that transforms the docbook to wiki output (wouldn't be surprised if
such a beast already exists) but the source should be Docbook or ODF.

Sincerely,

Joshua D. Drake

P.S. I am not actually suggesting ODF

Alvaro Herrera wrote:

Magnus Hagander wrote:

Looking at the state of many of our non-english FAQs today, I don't
put too much faith into a system that'll just show people "this is
not translated". I think it's more likely to get better if the
people can just edit the translations directly instead of having to
produce a patch (and to make that work, they have to set up a build
system for processing docbook which is certainly far from trivial
on some platforms), etc...

There are web platforms for editing POs.

Hold on a minute. You're saying only the english version would be in
Docbook, and then you'd use .po files? So how do I as an end user
actually *read* the FAQ then? I need to both process .po and Docbook?

I remain very unconvinced that making it that much more complex is
worth it.. But if someone sets up a complete system to test it, sure -
since I don't write *or* read any of the translated FAQs we should
obviously listen more to those who do.

//Magnus

Joshua D. Drake wrote:

Magnus Hagander wrote:

Alvaro Herrera wrote:

The FAQs are another matter however. I suggested some time back
moving those to DocBook XML. A friend was working on a script to
do the initial conversion automatically. The nice thing about it
is that we can then use the xml2po tools to create PO files for
translation. This means that translations are more easily kept up
to date. Are you open to this possibility?

What would be the advantage of keeping it in DocBook over the wiki?
One of the main advantages of keeping it on the wiki would be to
allow others to help out with the editing of them.

Two words:

print format

If we want to push the FAQ to the wiki, we should write a stylesheet
that transforms the docbook to wiki output (wouldn't be surprised if
such a beast already exists) but the source should be Docbook or ODF.

You're not actually claiming we have print format today, are you?

And have you actually *tried* printing something from the wiki? Doesn't
look so bad to me.

And do people really *print* something like a FAQ?

Anyway. If people want to build a more complex system to deal with the
user FAQs, be my guest. The developer FAQ is obviously a very different
thing from those.

//Magnus

Am Samstag, 19. April 2008 schrieb Alvaro Herrera:

The FAQs are another matter however. �I suggested some time back moving
those to DocBook XML.

The question is whether we consider the FAQ to be a document tied to a
PostgreSQL release (e.g., there is a separate FAQ applying to each release)
or whether it is a "global" document. In the former case, it should be in
CVS, in the latter it should be somewhere else. In my mind, it is quite
clear that it is the latter.

But while I am in favor of moving as much as possible of the developer
documentation to the wiki, I am not sure such a primary, user-facing document
should be in a wiki. Not because I am afraid of anyone being able to edit
it, but I am concerned about the impression this creates with (new) users.
Could we mirror it from the wiki to the "real" web site?

Magnus Hagander wrote:

Hold on a minute. You're saying only the english version would be in
Docbook, and then you'd use .po files? So how do I as an end user
actually *read* the FAQ then? I need to both process .po and Docbook?

The xml2po tools allow the reconstruction of translated XML files from
the translated PO.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

Alvaro Herrera wrote:

Magnus Hagander wrote:

Hold on a minute. You're saying only the english version would be in
Docbook, and then you'd use .po files? So how do I as an end user
actually *read* the FAQ then? I need to both process .po and
Docbook?

The xml2po tools allow the reconstruction of translated XML files from
the translated PO.

Again, this seems a whole lot more complex for very little gain to me.
But if you're willing to do the work, and can get the FAQ translator
onboard thinking it's easier than the wiki, be my guest...

//Magnus

Peter Eisentraut wrote:

Am Samstag, 19. April 2008 schrieb Alvaro Herrera:

The FAQs are another matter however.  I suggested some time back
moving those to DocBook XML.

The question is whether we consider the FAQ to be a document tied to
a PostgreSQL release (e.g., there is a separate FAQ applying to each
release) or whether it is a "global" document. In the former case,
it should be in CVS, in the latter it should be somewhere else. In
my mind, it is quite clear that it is the latter.

Agreed. I don't think we *ever* backpatch FAQ stuff, which is a clear
indicator it's the later.

But while I am in favor of moving as much as possible of the
developer documentation to the wiki, I am not sure such a primary,
user-facing document should be in a wiki. Not because I am afraid of
anyone being able to edit it, but I am concerned about the impression
this creates with (new) users. Could we mirror it from the wiki to
the "real" web site?

I'm sure we can find a way to do that. We do a lot of fairly ugly work
to mirror from the cvs tree to the website today...

For reference, the developer FAQ (which really is a different thing,
given the audience) now lives on the wiki at
http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
people think about that one, and get a "signoff" on if this should be
the main location for it, thus removing it from CVS. (We've already had
a couple of fixes go into it, so it's actually more up-to-date than the
one in CVS...)

//Magnus

Magnus Hagander wrote:

Alvaro Herrera wrote:

Magnus Hagander wrote:

Hold on a minute. You're saying only the english version would be in
Docbook, and then you'd use .po files? So how do I as an end user
actually *read* the FAQ then? I need to both process .po and
Docbook?

The xml2po tools allow the reconstruction of translated XML files from
the translated PO.

Again, this seems a whole lot more complex for very little gain to me.
But if you're willing to do the work, and can get the FAQ translator
onboard thinking it's easier than the wiki, be my guest...

Actually not only I have to convince the translator -- I have to
convince Bruce *as a first step*. I have tried in the past and failed.
Now he is open to discuss changing the format of the FAQs, so I suggest
this idea again, and here I get a ton of negative responses from guys
who have never had anything to do with the FAQ at all ...

I mean what interest does Josh Drake have on whether the FAQ is in SGML
or XML?

... and no response from Bruce, either.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Magnus Hagander wrote:

For reference, the developer FAQ (which really is a different thing,
given the audience) now lives on the wiki at
http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
people think about that one, and get a "signoff" on if this should be
the main location for it, thus removing it from CVS. (We've already had
a couple of fixes go into it, so it's actually more up-to-date than the
one in CVS...)

Signoff-By: alvherre@alvh.no-ip.org

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

On Mon, Apr 21, 2008 at 11:20 PM, Magnus Hagander <magnus@hagander.net> wrote:

For reference, the developer FAQ (which really is a different thing,
given the audience) now lives on the wiki at
http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
people think about that one, and get a "signoff" on if this should be
the main location for it, thus removing it from CVS. (We've already had
a couple of fixes go into it, so it's actually more up-to-date than the
one in CVS...)

Nice. My 0.02$ is that the wiki is a better place for the Dev FAQ.

I did notice that the section on vim settings doesn't mention anything
about the expandtab setting. Ideally this should be set to
noexpandtab (noet) to preserve tab spacing. I'll add it to the wiki
page, but feel free to revert it if you don't want it in there.

I also saw that the Dev FAQ still points to Bruce's personal patch
lists as the primary source for the current patch queue. Have we
reached the point where we can direct developers to
http://wiki.postgresql.org/wiki/CommitFest instead?

Cheers,
BJ

Magnus Hagander wrote:

Alvaro Herrera wrote:

Magnus Hagander wrote:

I remain very unconvinced that making it that much more complex is
worth it.. But if someone sets up a complete system to test it, sure -
since I don't write *or* read any of the translated FAQs we should
obviously listen more to those who do.

Isn't this what we do with the docs now?

Joshua D. Drake

On Mon, Apr 21, 2008 at 11:54 PM, Brendan Jurd <direvus@gmail.com> wrote:

I did notice that the section on vim settings doesn't mention anything
about the expandtab setting. Ideally this should be set to
noexpandtab (noet) to preserve tab spacing. I'll add it to the wiki
page, but feel free to revert it if you don't want it in there.

Oh, and I always set textwidth (tw) to 79 as well, to get automatic
line wrapping on comments.

Cheers,
BJ

Alvaro Herrera wrote:

Actually not only I have to convince the translator -- I have to
convince Bruce *as a first step*. I have tried in the past and failed.
Now he is open to discuss changing the format of the FAQs, so I suggest
this idea again, and here I get a ton of negative responses from guys
who have never had anything to do with the FAQ at all ...

I mean what interest does Josh Drake have on whether the FAQ is in SGML
or XML?

Uhh my response was a +1.

Joshua D. Drake