Thread: Ask for Help on Improving the FreeBSD FAQ

Ask for Help on Improving the FreeBSD FAQ

From
Gabor PALI
Date:
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


Re: Ask for Help on Improving the FreeBSD FAQ

From
"Joshua D. Drake"
Date:

On Fri, 2008-06-06 at 19:02 +0200, Gabor PALI wrote:
> Dear PostgreSQL Developers,

> Thank you for your help in advance.

I think you may want to be at pgsql-docs

Sincerely,

Joshua D. Drake


> 
> 
> Best Regards,
> 
> Gabor Pali
> FreeBSD Committer
> The FreeBSD Documentation Project
> 



Re: Ask for Help on Improving the FreeBSD FAQ

From
"Joshua D. Drake"
Date:

On Sat, 2008-06-07 at 03:35 +0200, Gabor PALI wrote:
> Hello Joshua,

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

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

Peter Eisentraut <peter_e@gmx.net>

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




Re: Ask for Help on Improving the FreeBSD FAQ

From
"Joshua D. Drake"
Date:

On Sat, 2008-06-07 at 03:46 +0200, Gabor PALI wrote:
> > Oh I apologize :). PeterE is pretty much lead doc dude around here:

> Yes, I would like to know more about:
> - 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.

> - how you do build and mark up the different versions (e.g. static and
> 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




Re: Ask for Help on Improving the FreeBSD FAQ

From
Gabor PALI
Date:
Hello Joshua,

Joshua D. Drake wrote:
> 
> On Fri, 2008-06-06 at 19:02 +0200, Gabor PALI wrote:
>> Dear PostgreSQL Developers,
> 
>> Thank you for your help in advance.
> 
> 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



Re: Ask for Help on Improving the FreeBSD FAQ

From
Gabor PALI
Date:
> 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.


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

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


Re: Ask for Help on Improving the FreeBSD FAQ

From
Peter Eisentraut
Date:
Gabor PALI wrote:
> - whether you do have any project-specific modifications for DocBook
> - 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.


Re: Ask for Help on Improving the FreeBSD FAQ

From
Gabor PALI
Date:
> 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 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