Thread: Documentation organization

I've been looking into ways to handle the User/Admin/Programmer vs
Integrated dichotomy a little better. I think the intergrated document as
we know it needs to go. There's too much weirdness in the order (e.g., the
tutorial coming after the FE/BE protocol, release notes somewhere in the
middle, etc.) that is created by just pasting together the "guides". Also,
the chapters are numbered differently, which makes referring to them by
number impossible.

But, it's not like I don't have a better idea. :-) DocBook has a <Set> as
a parent element of <Book>. This would look something like this:

<set>
 <title>PostgreSQL Documentation</>

 &user;
 &admin;
 ...
</set>

where &user and &admin would be the usual entities that contain <book>'s.

When you process this you get admin.html, user.html, etc. as usual, but
you also get a title page that contains links to all the "books". So this
would in essence be the integrated document, just another level added to
the click-hierarchy. (The ToC for the integrated document is way too long
anyway.)

This setup also allows us to make links across books in a transparent
fashion. For example, if I write `See also <XRef id="mvcc">' in the
administrator's guide it comes out as "See also Chapter 13 in the
PostgreSQL User's Guide", with hyperlink.

The question is how to make print documents from this. I haven't found a
way for Jade's RTF backend to split its output into several files. But it
should be possible to take this RTF document and just "save pages x-y" to
get the user's guide, "save pages y-z" to get the admin guide, etc. and
all the page numbers etc. should be in order.


At the same time I've also been pondering what kinds of books/guides we
need. The division that the integrated document already follows with its
"parts" seems like a good idea to me:

* User's guide (everything about query language)

* Administator's guide

* Interfaces guide (everything in src/interfaces, plus pgaccess, psql,
etc.)

* Programmer's guide (server-side programming, SPI, custom types,
functions, procedural languages)

* Developer's guide (to contribute to PostgreSQL)

* Tutorial

I also think we need to seperate out the

* Installation instructions

* Release notes (You really need these before installation or even
download, not after administration.)

Reference pages should be placed at the end of each document that they fit
into. E.g., postmaster in Administorator's guide, psql in Interfaces, etc.


Comments? Suggestions? Better ideas?


--
Peter Eisentraut                  Sernanders väg 10:115
peter_e@gmx.net                   75262 Uppsala
http://yi.org/peter-e/            Sweden

> Comments? Suggestions? Better ideas?

I can't argue with the statement that the overall organization is about
right. :)

I'm not sure how "set" will differ from "part" when it comes time to
split up the hardcopy, but it might be pretty easy (it partly depends on
how the RTF assigns the styles). Do you want to try to do
"postgres.sgml" as a set-based doc and see how it works? Or modify it
and commit it as postgres-set.sgml so we can carry along both until the
kinks are worked out?

> Reference pages should be placed at the end of each document that they
> fit into. E.g., postmaster in Administorator's guide, psql in
> Interfaces, etc.

Hmm. I think that this might be OK, but I'm worried that there will be
some "grey area" categories that make it hard to figure out which doc to
look in for the reference. psql is a good example: why should it be in
"Interfaces" (coding interfaces?) instead of "Applications"?

But we can also carry along a separate "references" document which
*does* integrate them all, as well as including them at the end of each
relevant doc. I'm pretty sure that if I had to choose one or the other
I'd choose to put them together.

                  - Thomas

Thomas Lockhart writes:

> I'm not sure how "set" will differ from "part" when it comes time to
> split up the hardcopy, but it might be pretty easy (it partly depends
> on how the RTF assigns the styles).

A "set" will cause the chapter and page numbering to restart in each
book, which is what we'd presumably want.

I will put something like I imagined together over the weekend and post
it on the web so you can take a look.

> But we can also carry along a separate "references" document which
> *does* integrate them all, as well as including them at the end of
> each relevant doc.

Good idea. Let's see how it would come out.


--
Peter Eisentraut                  Sernanders väg 10:115
peter_e@gmx.net                   75262 Uppsala
http://yi.org/peter-e/            Sweden