Content-Type: text/plain;
  charset="iso-8859-1"
From: Josh Berkus <josh@agliodbs.com>
Organization: Aglio Database Solutions
To: nolan@celery.tssi.com
Subject: Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread
Date: Mon, 23 Jun 2003 23:04:04 -0700
User-Agent: KMail/1.4.3
Cc: pgsql-advocacy@postgresql.org (\"'Advocacy PostgreSQL'\"),
	pgsql-general@postgresql.org ('PostgreSQL-general')
References: <20030624050732.2523.qmail@celery.tssi.com>
In-Reply-To: <20030624050732.2523.qmail@celery.tssi.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Message-Id: <200306232304.04070.josh@agliodbs.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