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