Thread: Documentation in book length

Documentation in book length

From
Peter Eisentraut
Date:
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


Re: Documentation in book length

From
Joe Conway
Date:
Peter Eisentraut wrote:
> 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.

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

> Compared to making the documentation easier to use and more "marketable" I
> think this is a price we have to pay.
>
> Thoughts?

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

Joe


Re: Documentation in book length

From
Tom Lane
Date:
Joe Conway <mail@joeconway.com> writes:
> Making the docs into one book should also allow better hyperlink
> 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

Re: Documentation in book length

From
Bruce Momjian
Date:
Tom Lane wrote:
> Joe Conway <mail@joeconway.com> writes:
> > Making the docs into one book should also allow better hyperlink
> > 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.

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
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

Re: Documentation in book length

From
Lamar Owen
Date:
On Thursday 02 January 2003 18:32, Tom Lane wrote:
> 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?

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


Re: Documentation in book length

From
"Marc G. Fournier"
Date:
On Thu, 2 Jan 2003, Lamar Owen wrote:

> On Thursday 02 January 2003 18:32, Tom Lane wrote:
> > 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?
>
> http://sources.redhat.com/rhdb/
>
> See the links on the left under 'RHDB 2.1 Documentation'.
>
> They are quite good.

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


Re: Documentation in book length

From
"Marc G. Fournier"
Date:
On Thu, 2 Jan 2003, Tom Lane wrote:

> 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.

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 ...

> 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?

Definitely ...


Re: Documentation in book length

From
Tom Lane
Date:
"Marc G. Fournier" <scrappy@hub.org> writes:
>> http://sources.redhat.com/rhdb/
>>
>> See the links on the left under 'RHDB 2.1 Documentation'.

> 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

Re: Documentation in book length

From
"Marc G. Fournier"
Date:
On Thu, 2 Jan 2003, Tom Lane wrote:

> "Marc G. Fournier" <scrappy@hub.org> writes:
> >> http://sources.redhat.com/rhdb/
> >>
> >> See the links on the left under 'RHDB 2.1 Documentation'.
>
> > 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.

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?


Re: Documentation in book length

From
Roberto Mello
Date:
On Thu, Jan 02, 2003 at 06:32:07PM -0500, Tom Lane wrote:
>
> 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?

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?

Re: Documentation in book length

From
Oleg Bartunov
Date:
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


Re: Documentation in book length

From
Peter Eisentraut
Date:
Joe Conway writes:

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

cd doc/src/sgml
gmake check

--
Peter Eisentraut   peter_e@gmx.net


Re: Documentation in book length

From
Peter Eisentraut
Date:
Roberto Mello writes:

> 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".

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?

--
Peter Eisentraut   peter_e@gmx.net


Re: Documentation in book length

From
Peter Eisentraut
Date:
Oleg Bartunov writes:

> 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.

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.

--
Peter Eisentraut   peter_e@gmx.net


Re: Documentation in book length

From
Peter Eisentraut
Date:
Tom Lane writes:

> 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?

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.

--
Peter Eisentraut   peter_e@gmx.net


Re: Documentation in book length

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> It's not particularly fair, but we should discuss it.  Either we
> 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
> documentation work in the release notes with the usual attribution?

Sure, the same way we credit significant code contributions.

            regards, tom lane