Subject: Documentation in book length

From: Peter Eisentraut <[email-masked]>
Date: Fri, 3 Jan 2003 00:08:49 +0100 (CET)

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-masked]

---

From: Joe Conway <[email-masked]>
Date: Thu, 02 Jan 2003 15:12:26 -0800

> takes a few seconds on modern machines and catches most mistakes.

That sounds great. How to you do the SGML syntax check?

> think this is a price we have to pay.

Making the docs into one book should also allow better hyperlink 
cross-referencing. That will be a welcome improvement.

Joe

---

From: Tom Lane <[email-masked]>
Date: Thu, 02 Jan 2003 18:32:07 -0500

> cross-referencing. That will be a welcome improvement.

Yes --- eliminating our silly "it's somewhere in that part"
cross-references is quite sufficient reason in my mind to abandon the
option of building the docs in sections.  If we have to build the whole
book every time, so be it.

BTW, the Red Hat RHDB group has spent a fair amount of time rethinking
the overall organization of the docs and trying to organize 'em in a
more logical order.  They'd like to contribute that work back so they
don't have to maintain a variant version of the docs.  Is this a good
time to think about looking over what they've done?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 2 Jan 2003 18:36:03 -0500 (EST)

> book every time, so be it.

I didn't even know we could build in parts.  I just build the whole
thing so merging them isn't a problem for me.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: Lamar Owen <[email-masked]>
Date: Thu, 2 Jan 2003 18:41:23 -0500

> time to think about looking over what they've done?

http://sources.redhat.com/rhdb/

See the links on the left under 'RHDB 2.1 Documentation'.

They are quite good.
-- 
Lamar Owen
WGCR Internet Radio
1 Peter 4:11

---

From: "Marc G. Fournier" <[email-masked]>
Date: Thu, 2 Jan 2003 21:00:04 -0400 (AST)

> See the links on the left under 'RHDB 2.1 Documentation'.

they look like our docs ... what is different?

---

From: "Marc G. Fournier" <[email-masked]>
Date: Thu, 2 Jan 2003 21:03:28 -0400 (AST)

> book every time, so be it.

Ya, shouldn't be a problem from the server side for doing such ... we're
in the process of adding a new server online that is "bigger and better"
then what we have online right now, and I'm going to be looking at moving
more stuff off of the current server used for postgresql.org ...

> time to think about looking over what they've done?

Definitely ...

---

From: Tom Lane <[email-masked]>
Date: Thu, 02 Jan 2003 20:04:25 -0500

> they look like our docs ... what is different?

They *are* our docs, just rearranged a bit.  I don't recall the details
of what was done, but comparing the tables of contents would probably
show you most of the work.

			regards, tom lane

---

From: "Marc G. Fournier" <[email-masked]>
Date: Thu, 2 Jan 2003 21:51:31 -0400 (AST)

> show you most of the work.

Well, since Peter is proposing a re-org of the docs into one book, do you
want to invite the RedHat docs guys to join us?

---

From: Roberto Mello <[email-masked]>
Date: Thu, 2 Jan 2003 21:08:40 -0700

> time to think about looking over what they've done?

Allow me to insert a note about adisappointment of mine here, which 
happenned when I browsed the Red Hat DB documentation a few weeks ago.

I noticed that, besides the content being modified in some places, the  
authorship of the documents had been completely removed from the
documents. Also I noticed "Copyright 2001 Red Hat" in the documents, which
made me wonder if that was really right, legally speaking.

The two examples I can give you are in the PL/pgSQL documentation, both
the initial document page
(http://www.redhat.com/docs/manuals/database/RHDB-2.1-Manual/prog/plpgsql.html)
and the Oracle porting document I wrote
(http://www.redhat.com/docs/manuals/database/RHDB-2.1-Manual/prog/plpgsql-porting.html)

As far as my understanding of the BSD license applied to documents allows
anyone to modify said documents, saved the copyright notices are left.
However, it is very uncool to remove authorship credits from the
documentation. I don't see how removing such credits will make the Red Hat
DB documentation look any better or more "professional".

-Roberto

-- 
+----|        Roberto Mello   -    http://www.brasileiro.net/  |------+
+       Computer Science Graduate Student, Utah State University      +
+       USU Free Software & GNU/Linux Club - http://fslc.usu.edu/     +
Hey, whats that beeping noise? Wheres that smoke coming from?

---

From: Oleg Bartunov <[email-masked]>
Date: Fri, 3 Jan 2003 15:04:31 +0300 (MSK)

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

> to get this down to one.  We have the following page count for each book

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

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 4 Jan 2003 11:29:04 +0100 (CET)

> That sounds great. How to you do the SGML syntax check?

cd doc/src/sgml
gmake check

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 4 Jan 2003 11:30:17 +0100 (CET)

> DB documentation look any better or more "professional".

It's not particularly fair, but we should discuss it.  Either we
consistently attribute every section or chapter, or we don't do it.  I
could probably put names on most chapters from memory and I wouldn't mind
it, but it does seem like an unusual thing to have names on only a few
sections.  Maybe it would be a good compromise to record significant
documentation work in the release notes with the usual attribution?

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 4 Jan 2003 11:30:56 +0100 (CET)

> GiST programming in russian but I didn't had a time to write it in english.

It is (nearly) always the time to add some docs.  There are existing
sections that describe interfacing extensions to indexes, which is
probably where you want to weave yours in.

---

From: Peter Eisentraut <[email-masked]>
Date: Sat, 4 Jan 2003 11:36:22 +0100 (CET)

> time to think about looking over what they've done?

Yes, we shall use them as an example of how not to do it.

I spend quite some time today to analyze their documentation arrangement,
but it doesn't make sense to me.  There are a couple of obvious
rearrangements and a couple of things we could think about if they were
briefly explained, but overall it looks pretty confused, to say it nicely.

---

From: Tom Lane <[email-masked]>
Date: Sat, 04 Jan 2003 11:05:06 -0500

Peter Eisentraut <[email-masked]> writes:
> consistently attribute every section or chapter, or we don't do it.

My inclination would be not to do it.  There are very few sections
(if any at all) that are truly the work of just one person anymore,
even if the original text was all by one hand.

> Maybe it would be a good compromise to record significant

Sure, the same way we credit significant code contributions.

			regards, tom lane