pg.ddx.io pgsql-docs@postgresql.org mailing list archivehelp / color / mirror / Atom feed
Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread 2+ messages / 2 participants [nested] [flat]
* Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread @ 2003-06-24 06:04 Josh Berkus <josh@agliodbs.com> 0 siblings, 1 reply; 2+ messages in thread From: Josh Berkus @ 2003-06-24 06:04 UTC (permalink / raw) To: nolan@celery.tssi.com; +Cc: pgsql-advocacy@postgresql.org 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 ^ permalink raw reply [nested|flat] 2+ messages in thread
* Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread @ 2003-06-24 07:05 nolan@celery.tssi.com parent: Josh Berkus <josh@agliodbs.com> 0 siblings, 0 replies; 2+ messages in thread From: nolan@celery.tssi.com @ 2003-06-24 07:05 UTC (permalink / raw) To: josh@agliodbs.com; +Cc: pgsql-advocacy@postgresql.org > ??? 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. Try accessing a HTML file on a Linux system from a PC-based browser. Unless you have some kind of file sharing software running, which I generally don't because the only times I've ever been hacked into they got in through file sharing ports, you can't get there from here. > 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 think the 'Nutshell' books are a different breed of cat, none of them have ever had indexes worth mentioning. > 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 -- I've been somewhat involved in three book projects (two textbooks and one rule book), in all three case the authors did their own index. Maybe I've just had a good run of luck on the O'Reilly books I've bought, or maybe I haven't bought as many of them in the last three or four years as I used to. -- Mike Nolan ^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2003-06-24 07:05 UTC | newest] Thread overview: 2+ messages (download: mbox mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2003-06-24 06:04 Re: [GENERAL] Documentation quality WAS: interesting PHP/MySQL thread Josh Berkus <josh@agliodbs.com> 2003-06-24 07:05 ` nolan@celery.tssi.com
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