SEO

Alvaro Herrera wrote:
> > >I don't think this sort of material belongs directly into the
> > > PostgreSQL documentation.
>
> Why not?

PostgreSQL documentation (or any product documentation) should be
factual: describe what the software does and give advice on its use.
This should be mostly independent of the external circumstances,
because people will still read that documentation three or four years
from now.

The proposed text is, at least partially, journalistic: it evaluates
competing ideas, gives historical and anecdotal information, reports on
current events, and makes speculations about the future. That is the
sort of material that is published in periodicals or other volatile
media.

At the summit, we resolved, for precisely these reasons, to keep the
journalistic parts on the web site, for clear separation from the
shipped product and for easier updates (and for easier reference as
well, because the PostgreSQL documentation is not the single obvious
place to look for it) and refer to it from the documentation.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

---------------------------(end of broadcast)---------------------------
TIP 4: Have you searched our list archives?

http://archives.postgresql.org

I was thinking of something similar to our encryption section:

http://www.postgresql.org/docs/8.1/s...n-options.html

The idea being to define issues like multi/single master, async vs,
sync, and mention the projects which are in each category.

---------------------------------------------------------------------------

Peter Eisentraut wrote:
> Alvaro Herrera wrote:
> > > >I don't think this sort of material belongs directly into the
> > > > PostgreSQL documentation.
> >
> > Why not?
>
> PostgreSQL documentation (or any product documentation) should be
> factual: describe what the software does and give advice on its use.
> This should be mostly independent of the external circumstances,
> because people will still read that documentation three or four years
> from now.
>
> The proposed text is, at least partially, journalistic: it evaluates
> competing ideas, gives historical and anecdotal information, reports on
> current events, and makes speculations about the future. That is the
> sort of material that is published in periodicals or other volatile
> media.
>
> At the summit, we resolved, for precisely these reasons, to keep the
> journalistic parts on the web site, for clear separation from the
> shipped product and for easier updates (and for easier reference as
> well, because the PostgreSQL documentation is not the single obvious
> place to look for it) and refer to it from the documentation.
>
> --
> Peter Eisentraut
> http://developer.postgresql.org/~petere/
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Have you searched our list archives?
>
> http://archives.postgresql.org

--
Bruce Momjian bruce@momjian.us
EnterpriseDB http://www.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

---------------------------(end of broadcast)---------------------------
TIP 1: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to majordomo@postgresql.org so that your
message can get through to the mailing list cleanly

Hi,

Bruce Momjian wrote:
> The idea being to define issues like multi/single master, async vs,
> sync, and mention the projects which are in each category.

You could even add shared-nothing vs. shared-disk nodes.

Generally I'd say it makes sense to 'educate' people, but does it really
make sense to explain all that if there is no replication solution for
most of these combinations?

I'd vote for an external (not in the documentation) information site
about replication solutions. There we can put all the information we see
fit (even 'journalistic' ones).

I might change my mind once we have multiple replication solutions
covering most situations. ;-)

I like what and how Chris wrote [1] - an overview over existing and
upcomming replication solutions.

Regards

Markus

[1]: I can't find Chris' original message. My answer to it is in the
archives, but not the original message. Why is that? (Thread view says
'message not available'). My answer contains Chris' text, though:
http://archives.postgresql.org/pgsql...7/msg00019.php

Peter Eisentraut wrote:
> Alvaro Herrera wrote:
> > > >I don't think this sort of material belongs directly into the
> > > > PostgreSQL documentation.
> >
> > Why not?
>
> PostgreSQL documentation (or any product documentation) should be
> factual: describe what the software does and give advice on its use.
> This should be mostly independent of the external circumstances,
> because people will still read that documentation three or four years
> from now.
>
> The proposed text is, at least partially, journalistic: it evaluates
> competing ideas, gives historical and anecdotal information, reports on
> current events, and makes speculations about the future. That is the
> sort of material that is published in periodicals or other volatile
> media.

I can see value in documenting what replication systems are known to
work (for some definition of work) with a given release in the
documentation for that release. Five years down the road when I'm
trying to implement replication for a client who's somehow locked into
postgres 8.2 (for whatever reason), it would be very helpful to know
that slony1.2 is an option. I don't know if this is sufficient
justification.

Including a separate page on the history of postgres replication to
date also makes some sense, at least to me. It should be relatively
easy to maintain.

If we do talk about replicatoin, then including a probably separate and
presumably quite static page on the taxonomy of replication seems
necessary. As Chris notes, the term replication by it'self is can mean
quite a number of things.

> At the summit, we resolved, for precisely these reasons, to keep the
> journalistic parts on the web site, for clear separation from the
> shipped product and for easier updates (and for easier reference as
> well, because the PostgreSQL documentation is not the single obvious
> place to look for it) and refer to it from the documentation.
>
> --
> Peter Eisentraut
> http://developer.postgresql.org/~petere/
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Have you searched our list archives?
>
> http://archives.postgresql.org

Hi,

Andrew Hammond wrote:
> I can see value in documenting what replication systems are known to
> work (for some definition of work) with a given release in the
> documentation for that release. Five years down the road when I'm
> trying to implement replication for a client who's somehow locked into
> postgres 8.2 (for whatever reason), it would be very helpful to know
> that slony1.2 is an option. I don't know if this is sufficient
> justification.

Please keep in mind, that most replication solutions (that I know of)
are quite independent from the PostgreSQL version used. Thus,
documenting which version of PostgreSQL can be used with which version
of a replication system should better be covered in the documentation of
the replication system. Otherwise you would have to update the
PostgreSQL documentation for new releases of your favorite replication
system - which seems to lead to confusion.

> Including a separate page on the history of postgres replication to
> date also makes some sense, at least to me. It should be relatively
> easy to maintain.

I agree that having such a 'replication guide for users of PostgreSQL'
is a good thing to have. But I think not much of that should be part of
the official PostgreSQL documentation - mainly because the replication
solutions are not part of PostgreSQL.

Regards

Markus

Markus Schiltknecht wrote:
> Hi,
>
> Andrew Hammond wrote:
> > I can see value in documenting what replication systems are known to
> > work (for some definition of work) with a given release in the
> > documentation for that release. Five years down the road when I'm
> > trying to implement replication for a client who's somehow locked into
> > postgres 8.2 (for whatever reason), it would be very helpful to know
> > that slony1.2 is an option. I don't know if this is sufficient
> > justification.
>
> Please keep in mind, that most replication solutions (that I know of)
> are quite independent from the PostgreSQL version used. Thus,
> documenting which version of PostgreSQL can be used with which version
> of a replication system should better be covered in the documentation of
> the replication system.

I would agree to this with the caveat that there needs to be something
in the postgres documentation that points people to the various
replication systems available.

> Otherwise you would have to update the
> PostgreSQL documentation for new releases of your favorite replication
> system - which seems to lead to confusion.

Yeah, updating the docs based on other software releases would suck.
How about "what works with a given release at the time of the release"?
Perhaps this could be limited to a pointer to the docs for such
replication systems, and maybe a very brief description (based on
Chris' taxonomy)?

> > Including a separate page on the history of postgres replication to
> > date also makes some sense, at least to me. It should be relatively
> > easy to maintain.
>
> I agree that having such a 'replication guide for users of PostgreSQL'
> is a good thing to have. But I think not much of that should be part of
> the official PostgreSQL documentation - mainly because the replication
> solutions are not part of PostgreSQL.

Arguably, neither are most of the procedural languages in the Server
Programming section of the documentation, and yet they're included. I
agree that it's improtant to keep the documentation from getting
cluttered up with stuff that's "not part of PostgreSQL". However, I
think the very fact so many people assume that there's no replication
for PostgreSQL simply because it's not mentioned in the documentation
shows that for many people replication is precieved as "part of" the
dbms. Even a single page in the documentation wich consists of
something along the lines of the following would help these folks find
what they're looking for.

"There are a number of different approaches to solving the problem of
replication, each with strengths and weaknesses. As a result, there are
a number of different replication solutions available for PostgreSQL.
To find out more, please refer to the website."

Andrew Hammond wrote:
> How about "what works with a given release at the time of the
> release"?

We just threw that idea out in the context of the procedural language
discussion because we do not have the resources to check what works.

> Arguably, neither are most of the procedural languages in the Server
> Programming section of the documentation, and yet they're included.

That is false. The documentation documents exactly those pieces of code
that we distribute.

> "There are a number of different approaches to solving the problem of
> replication, each with strengths and weaknesses. As a result, there
> are a number of different replication solutions available for
> PostgreSQL. To find out more, please refer to the website."

Well, that's what I've been talking about all along, and it has also
been the resolution at the Toronto meeting.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

---------------------------(end of broadcast)---------------------------
TIP 1: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to majordomo@postgresql.org so that your
message can get through to the mailing list cleanly

> > "There are a number of different approaches to solving the problem of
> > replication, each with strengths and weaknesses. As a result, there
> > are a number of different replication solutions available for
> > PostgreSQL. To find out more, please refer to the website."
>
> Well, that's what I've been talking about all along, and it has also
> been the resolution at the Toronto meeting.

Great. Is the above text sufficient for the documentation then, or does
anyone have a suggestion on how to say this better?

Drew