Date: Fri, 3 Jan 2003 00:08:49 +0100 (CET)
From: Peter Eisentraut <peter_e@gmx.net>
To: pgsql-docs@postgresql.org
Subject: Documentation in book length
Message-ID: <Pine.LNX.4.44.0301022356310.7742-100000@localhost.localdomain>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII

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?

-- 
Peter Eisentraut   peter_e@gmx.net