Re: [pgsql-advocacy] 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

---------------------------(end of broadcast)---------------------------
TIP 2: you can get off all lists at once with the unregister command
    (send "unregister YourEmailAddressHere" to majordomo@xxxxxxxxxxxxxx)