To: Bruce Momjian <bruce@momjian.us>
cc: Rafael Martinez <r.m.guerrero@usit.uio.no>, pgsql-docs@postgresql.org
Subject: Re: Documentation and explanatory diagrams 
In-reply-to: <201006302218.o5UMI7Y20379@momjian.us> 
References: <201006302218.o5UMI7Y20379@momjian.us>
Comments: In-reply-to Bruce Momjian <bruce@momjian.us>
	message dated "Wed, 30 Jun 2010 18:18:07 -0400"
Date: Wed, 30 Jun 2010 19:16:23 -0400
Message-ID: <19597.1277939783@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Bruce Momjian <bruce@momjian.us> writes:
> Rafael Martinez wrote:
>> I am sending you a proposal with 13 diagrams to include in the manual so
>> we can get an idea of how it will be. If it gets approved I will spend
>> more time creating and including other diagrams and improving the build
>> process for including figures into the manual.

> Great!

Where are the DIA sources for these?  It's impossible to evaluate how
maintainable these will be without seeing the source code.

>> If this proposal gets accepted we should work with:
>> - - Automatic generation of PNG files from DIA source under the build
>> process of the manual.

> I don't think we want to require dia to build the docs, so we are going
> to keep the dia and png files in CVS.

Yeah, probably, at least for the first go-round.

> Also, there are two images that need to be updated for every major
> release;  is that something we want to commit to doing?

-1 on that.  The timeline thing is *certainly* not worth the maintenance
effort, if indeed it even belongs in the docs at all (it looks more like
marketing material).  I think the lines-of-code diagram is not worth its
keep either.

One minor comment is that the page_layout diagram should say BLCKSZ not
8K, and the different-colored arrows in it don't really convey much ---
they need on-image labeling I think.

			regards, tom lane