public inbox for [email protected]  

help / color / mirror / Atom feed

From: Peter Eisentraut <[email protected]>
To: [email protected]
Subject: Documentation in book length
Date: Fri, 3 Jan 2003 00:08:49 +0100 (CET)
Message-ID: <[email protected]> (raw)

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   [email protected]

view thread (16+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected]
  Subject: Re: Documentation in book length
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox