Re: [DOCS] Replication documentation addition - Mailing list pgsql-hackers

On 10/25/06, Bruce Momjian <bruce@momjian.us> wrote:
> Joshua D. Drake wrote:
> > Bruce Momjian wrote:
> > > Tom Lane wrote:
> > >> "Magnus Hagander" <mha@sollentuna.net> writes:
> > >>> I think this is a good reason not to list *any* of the products by name
> > >>> in the documentation, but instead refer to a page on say techdocs that
> > >>> can be more easily updated.
> > >> I agree with that.  If we have statements about other projects in our
> > >> docs, we will have a problem with not being able to update those
> > >> statements in a timely fashion when the other projects change.
> > >
> > > I mention only Slony and pgpool as examples of replication types.  They
> > > seem to have risen to high enough visiblity to do that. I have not
> > > mentioned any other solutions.
> >
> > What about Slony-II or pgpool2? Which are fundamentally different from
> > their v1 counterparts (o.k. slony-ii isn't out yet but still).
> >
> > I +1 that we move to have all of the replication documentation pushed to
> > techdocs or other facility and just have a link from the docs.
>
> What I did was to mention Slony and pgpool as "examples", so people
> realize there are many other soluions.  It would be good to have a
> companion web site that could list them all, both open source and
> commercial.  That is going to take a lot more work, but I think would
> have great value, especially since our documentation will clearly
> outline the terms.  What you don't want to do is to throw up a list and
> have people try to figure out what solutions they cover.

I'm in quite an unique situation right now, working with a few DBAs
who have deep knowledge but no PostgreSQL background, so I have
a good view how PostgreSQL is perceived by people with fair knowledge
of other databases.

What I have noticed is a deep respect for community.  If they ask about
replication solution, and I tell about Slony, they ask if Slony is provided
with the postgresql-contrib. Well... no, and it won't be.  Then they look
back, think a while and say somethig on the lines of: well, $SOME_OTHER
_DATABASE was using external replication solutions so it is all right.

But then, before I talked with them, they did some quick research on
PostgreSQL and their perception was that there's no replication / replication
is shady in PostgreSQL.  It would be quite convenient to tell them:
"No replication? Did you actually read the manual? <here goes URL>"
Well, pointing them to slony page is a solution but of a lesser caliber
(how should they know about Slony anyway? They are newbies).
Pointing them at The Documentation is a Good Argument (and it may
cause them to look for some other information, like SQL syntax or
PostgreSQL-specific catalog views there, which is Good).

Enough background.

Bruce, I've read Your documentation and I was left a bit with a feeling
that it's a bit too generic.  It's almost as if it could be about just about
any major database, not PostgreSQL specific.  I feel that, when I'm
reading PostgreSQL docs I would like to know how to set up multi-master
replication with PostgreSQL not an explanation what a multi-master
replication is. It's not about the actual documentation content, but rather
on accents distribution.  Now it is something like: "These are the types
of replication solutions possible, some of them can be done with PostgreSQL",
I think it should be rather: "With PostgreSQL and some third-party tools you
can achieve such and such replication solutions, oh and by the way, research
is done on such and such replication method, but it's not a production quality
yet".

And I try to think as my DBA-mates would do if they read the documentation,
I'm not sure they would end up enlighted after reading the docs -- thay would
probably say: "hey, I knew that, it's well structured there, but I
still don't know
what should I use", or maybe "where can I read something about this slony
thing anyway?".

It may be my "closed thinking schema" though.  What I feel is that such
outsider, after reading these docs should end with "Aha! I should be using
Slony for my purposes".  Or pgpool, if it's what she needs.  I believe Tom's
remark that it does NOT belong in the PostgreSQL documentation is quite
right (though I wish there IS some reference to external replication packages,
mainly because over and over again I need to prove PostgreSQL CAN be
replicated, and it's not uncommon).  However I'm still unconvinced about
TechDocs -- TechDocs are good but still they are a bit scattered and
unorganised.  I am a PostgreSQL enthusiast, but it took me a while to
learn about them, and for newbies not biased towards PostgreSQL it may
take even more time.  If it is linked from within the documentation, random
DBAs might read it, and I wish they do.

Right now I am more and more biased towards an additional "documentation
book" for PostgreSQL, something like "DBA guide" or handbook.  In format
similar to the PostgreSQL documentation, but inside oriented around
configuring other tools around and together with PostgreSQL.  I shall send
here some drafts withing 10-days time to seed a discussion.  After all,
PostgreSQL is too big for just one documentation book. [1]
  Regards,     Dawid

[1]: Then, later, a programmer's handbook?  Deeper knowledge about fancy
stuff with Python, Perl and PgSQL? ;-)