Thread: Ask for Help on Improving the FreeBSD FAQ
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
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 >
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
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
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
> 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
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.
> 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