Skip site navigation (1) Skip section navigation (2)

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

From: Josh Berkus <josh(at)agliodbs(dot)com>
To: nolan(at)celery(dot)tssi(dot)com
Cc: pgsql-advocacy(at)postgresql(dot)org (\"'Advocacy PostgreSQL'\"),pgsql-general(at)postgresql(dot)org ('PostgreSQL-general')
Subject: Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread
Date: 2003-06-24 06:04:04
Message-ID: 200306232304.04070.josh@agliodbs.com (view raw or flat)
Thread:
Lists: pgsql-advocacypgsql-docspgsql-general
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

In response to

Responses

pgsql-docs by date

Next:From: Bruno BAGUETTEDate: 2003-06-24 06:35:33
Subject: RE : [GENERAL] interesting PHP/MySQL thread
Previous:From: Tony GrantDate: 2003-06-24 05:54:45
Subject: Re: [pgsql-advocacy] interesting PHP/MySQL thread

pgsql-advocacy by date

Next:From: Bruno BAGUETTEDate: 2003-06-24 06:35:33
Subject: RE : [GENERAL] interesting PHP/MySQL thread
Previous:From: Tony GrantDate: 2003-06-24 05:54:45
Subject: Re: [pgsql-advocacy] interesting PHP/MySQL thread

pgsql-general by date

Next:From: Bruno BAGUETTEDate: 2003-06-24 06:35:33
Subject: RE : [GENERAL] interesting PHP/MySQL thread
Previous:From: Tony GrantDate: 2003-06-24 05:54:45
Subject: Re: [pgsql-advocacy] interesting PHP/MySQL thread

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group