Re: Documentation and explanatory diagrams

On Fri, Jul 2, 2010 at 6:07 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> Marc G. Fournier wrote:
>> On Fri, 2 Jul 2010, Bruce Momjian wrote:
>>
>> > I am afraid if we don't enable dia by default then we will end up with
>> > production documentation without images.  I think we have to default dia
>> > to on, and give a reasonable error when it doesn't exist, and mention
>> > how to turn it off.
>>
>> Okay, I have no problem with either default on or off ... but ... won't th
>> efailure to have prod documentation with images be my fault?  or am I
>> missing something else here?
>
> The point is you will have to explicitly turn off dia/images to build
> without images.  That should make anyone building production docs always
> generate images, unless they override the default.

Is it at all practical to ship the PNGs as well as the DIA files in
CVS, and make rebuilding the PNGs from the DIAs a separate step?

Also, I think we need to review these images carefully before adding
any of them into our docs. 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?).

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

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.

The pg_dir_layout image seems like it would work equally well (and
maybe better) as text.

The pg_standby image appears identical to the file_based_log_shipping image.

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

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.

The tablespaces image labels the toplevel entity "PGCluster" but
doesn't use the "PG" prefix on any of the other items. That seems
inconsistent.

On the vacuum image, I don't know that the terms "active" and "expire"
are really the best terminology.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company