Re: Is Oracle the worst-documented product of all time?

Richard Burton wrote:

> I'm about a month into Oracle..

This is a very good place to start when replying to your mail. Hold this in mind when you get to the end of my reply.

> Let me preface this diatribe by saying where I'm coming from. I'm an
> accomplished programmer in various languages and platforms. My work
> has won numerous honors and awards, including "Editor's Choice" in PC
> Magazine. However, I'm a complete newbie (or at least I was a few
> months ago) at SQL and Oracle. I'm typically able to get up to speed
> on new systems very quickly. This was not the case with Oracle, and
> I'm well aware I've made a lot of brainless mistakes; incorrect
> assumptions, and have often been guilty of lacking patience &
> dilligence, however I don't believe I could possibly be near the low
> end (in terms of competence & attention span) of those who
> might be preparing to enter the Oracle world.
>

Hey, we are all award winners. So let's just deal with your problems...

> First and foremost, I have to admit that most of Oracle's products are
>
> very well designed. The performance and stability seems to be way
> above average, which IMO probably has the most to do with Oracle's
> success. However, on the other side, I'm appalled at how
> unnecessarily convoluted the support and education process is. I
> have yet to take any Oracle classes, but I don't feel that this should
>
> be a prerequisite to being able to be productive with the world's most
>
> popular database system. If I'm wrong, then I feel this is a weakness
>
> in the company's marketing strategy.
>

OK, next time you fly, insist on a pilot with NO TRAINING. (Ps. I'm a ex-pilot, and I wouldn't recommend that.)

> OTOH, I'm quickly starting to speculate that Oracle may end up making
> more money from support-related services than they do from selling
> products. If this is the case, then perhaps all of these faux pas are
>
> actually, carefully orchestrated in order to stimulate revenue. I
> can't say I'm very thrilled with this realization, but there are
> so many glaring ommissions and bad documentation, that it must be the
> case, and I think it's pretty sad.
>

Consulting services can be a great - and cost effective - way on getting up to speed on a project and making sure you are doing it right. I don't see a problem.

> Nonetheless, I'll share some examples of my gripes and solicit
> comments:
>
> * Why is the majority of Oracle's documentation exclusively on CD-ROM?
>
> Am I the only person who finds this incredibly annoying? I can
> understand that, if for example, the company can't afford to print so
> many manuals (yea, that must be it), or maybe it's because they want
> to keep their docs so timely that electronic publishing is the best
> way of providing support? I don't think so considering I ordered
> software last month, and the documentation CD-ROM they
> sent me was almost a year old!
>

Order the Oracle manuals as hardcopy. I have used Sybase, Informix and Oracle. Oracle's manuals are the BEST I HAVE EVER SEEN FOR ANY DATABASE. You also have the option of the Oracle Press books which are also excellent, and cheap. There are also many third party books.

> * Let's confuse them some more dept: I ordered the NT version of the
> Oracle server - ok, it installed nicely (and btw, one really nice
> thing I must say is that the OraInst program is well done), however in
>
> the docs there are various references to programs like SVRMGR.EXE,
> SQLDBA, SQL*Loader, etc. Of course if you look for these programs or
> type the filename at the command prompt as the docs suggest,
> they don't seem to be there, yet OraInst says they're installed. Ok,
> so where are they? Well after a rather arduous process, I
> discovered that many of these programs have been arbitrarily renamed
> to files like: SVRMGR23.EXE and SQLLDR73.EXE. Very nice. What
> bonehead came up with this idea? These programs typically display
> their version numbers upon execution. Why would you need to change
> the filename with every release? Does Oracle drug test their product
> managers? They should.
>

You can install multiple versions of Oracle on most platforms, hence the naming differences in some cases. Try reading the platform specific documentation and the release notes. Oh, and try the 'dir' command.

> A classic example of Oracle's obvious inability to properly document
> their systems can be found in one of their most popular and recent
> publications, "Oracle, The Complete Reference" - how ironic!
>
> * In general, this publication is a good representative of Oracle
> publications, that is, it's unnecessarily convoluted, very short on
> useful examples, and often includes references to things which aren't
> explained nearby (if at all). While containing lots of useful
> information, the manner in which the book is organized
> is so bad that it's laughable, and pretty sad at the same time. As
> expected, the first section of almost every Oracle publication starts
> with tons of fluffy propoganda on how wonderful and powerful Oracle
> is. *yawn*
>
> The first half of the book moves like a tutorial and introduction to
> Oracle, unfortunately the logic of how information is presented leaves
>
> a LOT to be desired.
>
> For example, I don't understand why the tutorial on creating tables is
>
> in Chapter SIXTEEN, following chapters such as, "Some Complex
> Possibilities", and "Advanced Use of Functions and Variables." You
> can be quite confident that all your possibilities will be complex
> when you haven't yet figured out how to create a table! Once again,
> I want to know what kinds of mushrooms the technical writers are
> putting on their pizzas!
>
> * Try finding a list of error codes and their meetings in this
> "reference" - I guess that's perhaps too esoteric a subject to
> include? How many other language references
> do you think leave out error codes and explanations?
>
> * Look up something like the function TO_CHAR() in the reference,
> which requires a 'format' string. Notice that there is no associated
> information on the usage of the format string. If someone wants to
> look up the TO_CHAR() function, what do you think they're going to be
> interested in finding out 99% of the time? That's right, the legend
> of the format string. Is it there? No. Is there any indication
> of where this information can be found? Not really. However, if
> you're dilligent you can look at the fourth entry in the "See Also:"
> reference, skip back 800+ pages to "Chapter 7", skim through, and you
> find some of the info. If this book was the basis of a scavenger
> hunt, it would be quite entertaining and fun.
>
> The above is representative of most of this "reference." Information
> is incomplete and unorganized all over the place.
>

Many of the sub-clauses are listed separately from the main commands to reduce the size of the manual. OK? BTW, I have recommended this book to many of my clients as AN ADDITION, NOT A REPLACEMENT FOR their normal full Oracle documentation set. They have ALL been very happy with it. Oracle is a large product - would you prefer one, 10,000 page book?

> * This is one of my favorites: In the heading for the language
> reference, there's a section entitled "Products" which apparently is
> supposed to give you an indication of which products support the
> associated statement. Unfortunately, in many of the listings, the
> word, "All" is listed. Is that ridiculous or what? This essentially
> guarantees that the book will likely be obsolete before it's even off
> the press - or is this yet another example of Oracle's "brilliant"
> marketing tactics?
>

Er, read any books on Java, A.N.Other database, etc., etc. lately? They are all out of date by the time they hit the shelves. That's why you read the release notes, the proper documentation that comes with the product, use Tech Support and use the Internet.

> * Most obnoxious reference: "Because it isn't cloaked in arcane
> language that only systems professionals can comprehend, ORACLE
> fundamentally changes the nature of the relationship between business
> and systems people. Anybody can understand it. Anybody can use it."
> Oh yea!!! Perhaps this is true, IF you take out any reference
> to "ORACLE" and replace it with "SQL", and you out-source the
> technical writing to people who HAVEN'T had umpteen million years of
> experience with Oracle and assume everyone else reading has as well.
>

You are taking the book out of context. This was meant as a reference against older, pre-relational databases. Read the book properly.

> * To be fair, I should also point out that the book "Oracle Databases
> on the Web", published by Corols Group Books, is almost as bad. This
> book spends way too much time on mundane things such as Oracle's lame
> encapsulation of html packages, and virtually no information on more
> important packages such as UTL_FILE - I guess they figure file i/o is
> not important in a web database? In fact, the only reference in
> this books index to "file" is as in "file transfer protocol" - good
> grief - this book isn't on Oracle - it's an Internet tutorial! The
> index has references to "Gallium Arsenide" but not
> "File I/O". What is with these Oracle people? Are they all nuts??
>
> Oracle manages to take a rather easy language and cloak it in some of
> the worst documentation produced on the planet. This obviously
> explains why DBAs command such high salaries; who has the patience to
> dance through megabytes of online manuals, thousands of pages of
> printed books, hours of classes, and hours of tech support to build a
> simple database? One thing's for sure, DBAs obviously have an
> unparalleled level of tolerance and patience - a very noble quality.
>
> In closing, I find it a shame that such good products are so darn
> difficult to learn when they don't need to be. It's true, once you
> get up to speed with Oracle, it becomes much easier - but there is no
> excuse for the horrible, horrible, horrible documentation!!!!

Well, sorry I have to disagree with most of what you state. Yes, the Oracle documentation is sometimes out-of-date and a *little* disorganised in places. Try a few competitive products and then see how bad Oracle is...

Look, Oracle is a large product. You can do a *lot* with it. Take some more time to LEARN and then rethink everything you put in this mail. I'm sure you'll find much of it untrue and extreme, coming purely from not having learnt the product properly. If you don't want to take Oracle training, get in a consultant to help you - I'm sure you'll find most of you problems aren't that big an issue.

Steve Phelan. Received on Tue Jul 08 1997 - 00:00:00 CDT