Re: Documentation and explanatory diagrams

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 07/03/2010 01:02 AM, Robert Haas wrote:

>
> Also, I think we need to review these images carefully before adding
> any of them into our docs.

I agree with this. I didn't want to use a lot time with the diagrams
until everything is decided and we agree to have diagrams in the
documentation.

They are a proof of concept, different diagram types for different parts
of the documentation. They all need to be reviewed if they are going to
be used.

If we go for having diagrams, we should:

- - Create a TODO list with the diagrams we would like to have and where.
- - Define a procedure and rules to send diagrams patches: how to send,
review, give feedback, back to send and final commit.
- - Define some guidelines about how to create a diagram, colors to use,
key information, etc.

We should also remember the users of our documentation:

1) DBAs
2) Application Developers
3) Newbies who want to learn postgres
4) People interested in postgres internals

I think, most of our users are 1) or 2) but certainly different users
need different types of diagrams.

> For example, I'd dispute the picture of the
> world shown on the file_based_log_shipping.png image; that's certainly
> not the only way to set it up (the archive needn't be on the primary
> node, right?).
>

It is not the only way of shipping files but it is certainly the safest.
Getting the files to ship from another source than the arch directory in
the primary is a disaster waiting to happen if something happens to the
process/mechanism that ships files, and this jobs is delayed or fails.

> The image that is called hot_standby is really showing a combination
> of SR + log shipping. It has nothing to do with Hot Standby.
>

Well, what is HS without SR + log shipping. Again, this is a typical
diagram for a DBA. What they need is an overview on how HS looks like
with all the components we suggest they should use when using HS.

A diagram about HS with internal information for a developer will be
completely different.

> The page_layout image is kinda confusing - I can tell what the purple
> and brown arrows are supposed to represent, but only because I already
> know what they're supposed to mean.
>

Typical example of what Heikki said in another message. All diagrams of
this type must have a key explaining the boxes/arrows.

>
> The pg_standby image appears identical to the file_based_log_shipping image.
>

They are not the same. One uses pg_standby and the other one the
internal mechanism in postgres to get the wal files to restore. Two very
different and incompatible ways of getting the same result, well
documented in the manual.

> The pgclient_server image is a mishmash of concepts with no unifying theme.
>

Typical diagram for a DBA. They need diagrams that give an overview of
the components/parts involved in the system they are administrating. The
top half of the diagram is just a representation of what is explained in
the section of the documentation where this diagram was suggested to be.
The bottom half is just a representation of the main parts involved in
the saving/getting data from disk/memory.

> The streaming_replication image is technically not correct. WAL
> sender reads from disk - PostgreSQL doesn't duplicate the WAL as it's
> generated. It also makes it look like WAL sender/reciever are not
> part of PostgreSQL, which of course isn't the case.
>

Again, typical diagram for a DBA with an overview of components and how
they interact with each other. They don't care where the wal sender gets
the WAL information, they care that the system has two processes talking
with each other and sending information between nodes. After testing SR,
I can say that the secondary node generates wal files under pg_xlog when
using SR.

regards,
- --
Rafael Martinez, <r(dot)m(dot)guerrero(at)usit(dot)uio(dot)no>
Center for Information Technology Services
University of Oslo, Norway

PGP Public Key: http://folk.uio.no/rafael/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)

iEYEARECAAYFAkwxlm4ACgkQBhuKQurGihSQtwCfVG7tn0rmf+TlrwgShFFYXhsB
PYMAoKLrgHSdhiP7p1p1yHKO5Mny6BSw
=BPlU
-----END PGP SIGNATURE-----