Re: guidance sought for beginning Oracle DB doc

["Steven J. Owens" <puff -at- netcom -dot- com>]

kimber_miller -at- acs-inc -dot- com writes:
 
> I am beginning a project in which I'm going to create a sizeable
> technical reference for Oracle DBAs and developers. It's my first
> Oracle project, and I'd be grateful for any bits of advice any of
> you care to toss out.

     I'm not sure precisely what you're doing; whether you're writing
books about Oracle itself, or about an Oracle application, or what.

> I do have a few specific questions:
 
> 1. Is there a particular reference book/tool/tutorial that you do or
> do not recommend? I know Oracle is a complex application. I'm
> looking for something to which I can refer and understand general
> and specific topics, but which won't overwhelm me. Possible??

     Believe it or not, the _Oracle for Dummies_ book is surprisingly
well written.  A lot of the dummies books are easy only because
they're shallow, but the Oracle book isn't bad.  A bit overly focused
on the PC version of Oracle, but then again that's not a bad
assumption for a Dummies book to make.  Unix folks have other sources
of info, and are more likely to be able to find their way to more
hardcore sources, in any event.

     I looked into the O'Reilly Oracle books but heard mixed reviews,
and then my pressing need passed.  If I jump back into that frying
pan, I might pick them up anyway, just to have a coherently organized
set of books.

     The Oracle Press books, authorized by Oracle are canonical, but
in my opinion poorly organized and poorly written.  Still, that's the
horse's mouth, so to speak.

     Phil Greenspun has some Oracle articles on his website, including
an amusing "Caveman Oracle Tuning" article that points out some of the
major flaws o fthe database.  Surf to www.photo.net, then look for his
personal web pages.  I don't know if his new book (check the web site)
has anything covering Oracle, but if it does, there's an online
version of the book at his site and if you find it helpful enough,
it's probably worth getting the printed version.

> 2. Has anyone created an online version of a technical reference?
> I'd like to approach it this way and am in the process of arranging
> time to poll the DBAs and developers here, who will be only part of
> my audience. Win-Help style or HTML-Help style? Web-style? The
> online tool would be available on a server now and <someday> on the
> intranet site I am supposed to develop in my "down time."

     If the online version's purpose is ready reference during
problem-solving, bear that in mind, and also the circumstances in
which it will be used.  It's not much use to have a set of database
manuals that require exclusively a UNIX workstation equipped with a
CD-ROM and Xwindows. (Well, these days you're a lot more likely to
have that than back when I ran into that little problem, but).

     I'd suggest pure HTML in general, though make sure you generate
an excellent index and table of contents.
 
> 3. If you have developed a tech reference specifically for the
> database layer of an application--are there any pointers that you'd
> like to pass along?  I appreciate your time with this. Thank you for
> sharing.

     When in doubt, follow the data.  I can't count how many times
I've wanted to strangle the tech writers for a particular database
application for not including a chapter on the structure of the
database, what each table is used for, the columns, what interacts
with what, etc.  Of course a lot depends on your anticipated audience,
both for your software and your document.  

     In general, though, my experience has been that most of the time
the people installing and configuring the software really need to know
as much as possible about how it works and what it needs to do.  Most
of the time, particularly with major enterprise applications, it's
going to be deployed in ways you can't even anticipate, let alone plan
ahead and provide for.

Steven J. Owens
puff -at- netcom -dot- com