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

>> 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.)

I don't think that's an accurate anology. I'm talking about the ability to learn the system - it's not a life-or-death situation. There are plenty of tools available for mission-critical applications, and 99% of them don't require you to fly off somewhere and sit in a classroom in order to figure out how they are used.

> 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.

With all due respect, I absolutely disagree with you. I think Oracle's manuals and documentation are the worst in the industry. I think they should re-assign all their technical writers to mowing the lawn in front of their offices - and even in that situation, I think they'd probably need some supervision. But hey, that's my opinion - I ran a commercial software company, and I know first-hand that the quality of the documentation has an impact on the amount of technical support you must provide. Since Oracle charges for tech support, they obviously aren't that concerned about bad docs.

This underlines the original point I made, which is that I'm certain once I'm up to speed with Oracle, I'll forget how frustrating the learning process was, and I don't want to do that. Resources on Oracle technology are spread all over the place - you can typically find 20% of the info in one book, 20% in the online manuals, 20% on the MetalLink site, etc... It's like a huge scavenger hunt to put together all the pieces to figure out how things work. I don't understand why it has to be like that.

>> 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?
>
>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.

That still doesn't explain why the manuals make reference to programs being named one thing, when they are in fact different on disk. I probably have 40+ Oracle-related directories on my system and typing DIR is not my idea of an efficient method of figuring out what arbitrarily changes they've sprung on me, even after reading platform-specific docs. Besides, this is what I'm talking about - I have better uses for my time; I shouldn't have to hunt around on the disk for files.

>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?

How about one centralized documentation database that is fully searchable? Don't even get me started about Oracle Book - you need a reference manual in order to access the reference manuals!! You can't tell which book file relates to which topics without a key - and you can't seem to search across multiple books for what you're looking for. There are books relating to individual products, then there are ambiguous books like, "Application Developers Guide" which you have to guess which products it covers. And on my machine, the print function in Oracle book doesn't seem to be available.

>> * 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.

That still doesn't justify the ridiculous use of the word "All". Oracle could list the main products and version numbers, or some sort of icon or key that a person could tell exactly what products were available at the time of the book printing in order to know what is supported. It's irresponsible what they've done in this respect.

>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.

I'm sure they won't be that big of an issue once I get more experience under my belt. That's not the point. I have written computer manuals. I've provided tech support for software. I am appalled at how unorganized the product documentation is. Just because Oracle is a "large" product doesn't mean that the information has to be so unorganized. They can't even standardize on a single format! Some manuals are in PDF, some are in HTML, and others are in their proprietary book format. Not to mention that other information resources are in printed publications and on password-protected web sites.

In contrast, take a look at Microsoft's SDK documentation - it's put out in volumes and clearly organized. It's surely no less complicated than Oracle, and MS has subscription CDROM services with updated documentation - all much better organized. I'm no fan of MS, but they certainly have better technical writers than Oracle. Received on Tue Jul 08 1997 - 00:00:00 CDT