From: Josh Berkus <josh@agliodbs.com>
To: nolan@celery.tssi.com
Cc: pgsql-advocacy@postgresql.org
Subject: Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread
Date: Mon, 23 Jun 2003 23:04:04 -0700
Message-ID: <200306232304.04070.josh@agliodbs.com> (raw)
In-Reply-To: <20030624050732.2523.qmail@celery.tssi.com>
References: <20030624050732.2523.qmail@celery.tssi.com>
Nolan,
> And my pet peeve of the month is software source distributions that
> include the documentation ONLY in HTML, which is OK IF you have Apache
> running on the system you're building the sources on and are willing to
> make the documentation directory available to Apache, but otherwise
> they're very hard to use.
??? You can look at an HTML file directy with any browser. If you're SSH-ing
in to a remote system, use Lynx. Though I agree that providing both man and
html would be nicer.
> And while i'm on the subject, the only book (hard copy) I've got on
> PostgreSQL is the O'Reilly 'Practical PostgreSQL' book, now a bit dated,
> which has one of the worst indexes I've seen in a computer manual in years.
> It may be the worst index I've ever experienced in an O'Reilly book.
O'Reilly seems to be pretty hit-and-miss on this account. The Perl books are
well-indexed, but "SQL in a Nutshell" has *no* index, perhaps because
O'Reilly thought (wrongly) that it didn't need one because of the
dictionary-like format. The O'Reilly label is not a guarentee of quality,
just a general indicator.
> I know
> that indexes are the last thing authors want to do (both literally and
> figuratively), but a good index makes the rest of the book much better.
Authors seldom do the indexes themselves, as indexing is a black art known to
few (and I have yet to see a really good index prepared by the author --
sorry, Bruce) Most frequently, the publisher hires a professional indexer and
takes the cost out of the author's advance. When you find a really good
index, you know that either:
a) the author really cares about indexes;
b) the publisher offered to pay for or split the cost of indexing, or at least
made it a requirement of the book contract.
Obviously, the publisher can really influence things through (b), so if I find
a badly indexed book (and in my estimate 70% of tech books are badly indexed)
I blame the publisher first.
--
Josh Berkus
Aglio Database Solutions
San Francisco
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: josh@agliodbs.com, nolan@celery.tssi.com, pgsql-advocacy@postgresql.org
Subject: Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread
In-Reply-To: <200306232304.04070.josh@agliodbs.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox