Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread

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