Subject: Ask for Help on Improving the FreeBSD FAQ

From: Gabor PALI <[email-masked]>
Date: Fri, 06 Jun 2008 19:02:10 +0200

Dear PostgreSQL Developers,

Together with some other committers I am working on a FAQ Renewal
Proposal for making the FreeBSD FAQ better, i.e. make it easier to
maintain and to keep updated, make it more interactive and so on. It has
been suggested that you have a solution for these problems (e.g.
handling user comments) and you also use DocBook for documentation.

We would be happy to learn more about your documentation system and to
cooperate with you, to discuss your opinions and experiences on the
topic. Maybe we can solve the remaining problems together and improve
quality of the documentation of both projects.

Thank you for your help in advance.

Best Regards,

Gabor Pali
FreeBSD Committer
The FreeBSD Documentation Project

---

From: "Joshua D. Drake" <[email-masked]>
Date: Fri, 06 Jun 2008 13:03:22 -0700

> Thank you for your help in advance.

I think you may want to be at pgsql-docs

Sincerely,

Joshua D. Drake

---

From: Gabor PALI <[email-masked]>
Date: Sat, 07 Jun 2008 03:35:05 +0200

Hello Joshua,

> I think you may want to be at pgsql-docs

I got this advice from Bruce Momjian, because we are mainly interested
in the implementation, not in the documentation itself :) As far as I
know, this list is for developers, and -doc is for users. Do you know
who is responsible for the implementation of the documentation?

Thank you,
:g

---

From: "Joshua D. Drake" <[email-masked]>
Date: Fri, 06 Jun 2008 18:37:03 -0700

> who is responsible for the implementation of the documentation?

Oh I apologize :). PeterE is pretty much lead doc dude around here:

Peter Eisentraut <[email-masked]>

But I might be able to help you as well. Do you have a specific are of
interest besides the fact that we use Docbook?

Sincerely,

Joshua D. Drake

---

From: Gabor PALI <[email-masked]>
Date: Sat, 07 Jun 2008 03:46:53 +0200

> Oh I apologize :). PeterE is pretty much lead doc dude around here:

Thank you, I will also contact him, but I think he will got all these mails.

> interest besides the fact that we use Docbook?

Yes, I would like to know more about:
- how you do implement the user comments on your web pages,
- whether you do have any schedule for merging these comments,
- how you do build and mark up the different versions (e.g. static and
interactive per versions) of the documentation,
- whether you do have any project-specific modifications for DocBook
- what other tools you do use for creating documentation

Thank you for your answers in advance,
:g

---

From: "Joshua D. Drake" <[email-masked]>
Date: Fri, 06 Jun 2008 18:51:41 -0700

> - how you do implement the user comments on your web pages,

Ahh yes this is not actually a doc question, so you are in the right
place. These are stored in a PostgreSQL database and sent through a
moderation queue. If the comment is appropriate we include the
information in the next version of the docs.

The website svn is available here:

https://pgweb.postgresql.org/

> - whether you do have any schedule for merging these comments,

Per each major release.

> interactive per versions) of the documentation,

That I can't answer.

> - whether you do have any project-specific modifications for DocBook

We have specific stylesheet changes yes, you can find them in our
src/doc if you download a tarball.

> - what other tools you do use for creating documentation

Just docbook and jade :) (and dsssl)

Sincerely,

Joshua D. Drake

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 7 Jun 2008 15:09:23 +0200

> - what other tools you do use for creating documentation

Most of our documentation building technology was actually inspired and/or 
copied from the FreeBSD project.  So I think chances are low you will find 
anything here that you don't already have.  The integration with the web site 
and so on are different, but other people have already commented on that.

I suggest you take a look at the code (Makefile and so on) in doc/src/sgml.

---

From: Gabor PALI <[email-masked]>
Date: Sun, 08 Jun 2008 10:41:36 +0200

> and so on are different, but other people have already commented on that.

I see. I would like to ask how many user comments you do receive usually
(per week, per year or per release), whether it is hard to filter them
and maintain the documentation based on them. There is huge question in
our lines regarding this. (``How much does the interactivity cost?'')

Thank you very much,
:g