Обсуждение: Documentation in book length
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
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
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
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
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
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?
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 ...
"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
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?
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?
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
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
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
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
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
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