Date: Fri, 3 Jan 2003 15:04:31 +0300 (MSK)
From: Oleg Bartunov <oleg@sai.msu.su>
To: Peter Eisentraut <peter_e@gmx.net>
Cc: pgsql-docs@postgresql.org
Subject: Re: Documentation in book length
In-Reply-To: <Pine.LNX.4.44.0301022356310.7742-100000@localhost.localdomain>
Message-ID: <Pine.GSO.4.44.0301031500500.4544-100000@ra.sai.msu.su>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII

Is't a time to add some docs ? We have written some documentation about
GiST programming in russian but I didn't had a time to write it in english.

	Oleg
On Fri, 3 Jan 2003, Peter Eisentraut wrote:

> The other day I had a meeting with a publisher who wants to put out the
> PostgreSQL documentation as a book.  One of the problems we discussed was
> that the PostgreSQL documentation comes as 6 "book" documents, and we need
> to get this down to one.  We have the following page count for each book
> based on the 7.2 PDFs:
>
> Admin		 171
> Developer	  85
> Programmer	 362
> Reference	 272
> Tutorial	  35
> User		 170
> --------------------
> Total		1095
>
> If we ignore some of the redundancies (e.g., the same preface in every
> book) and assume a denser typesetting style that is more like commercial
> books we get to around 700 pages.  Compare this to some other prominent
> documentation of open-source software that you can buy as a book:
>
> FreeBSD Handbook	653 pages
> GIMP Handbook		658 pages
> MySQL Handbook		744 pages
>
> So based on publishing standards, so to speak, it would seem to make sense
> to present the existing PostgreSQL documentation as just one book.
>
> Now having that in mind and considering the all too often heard complaint
> that it is too difficult to find anything in the PostgreSQL documentation
> I would like to tackle this reorganization at the source level. Initially,
> I think we could concatenate the existing "books" approximately in the
> order they are right now, relabelling them as "parts".
>
> I know one possible objection is that it takes too long to build the
> complete documentation set.  But you can do an SGML syntax check that
> takes a few seconds on modern machines and catches most mistakes.
> Compared to making the documentation easier to use and more "marketable" I
> think this is a price we have to pay.
>
> Thoughts?
>
>

	Regards,
		Oleg
_____________________________________________________________
Oleg Bartunov, sci.researcher, hostmaster of AstroNet,
Sternberg Astronomical Institute, Moscow University (Russia)
Internet: oleg@sai.msu.su, http://www.sai.msu.su/~megera/
phone: +007(095)939-16-83, +007(095)939-23-83