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

Steve Phelan wrote:
> ...
> Look, to get back to what we've been trying to tell you: Oracle is a
> large and sophisticated product, so get some training and/or some
> consultancy - it really won't kill you, take my word for it - and buy
> the Oracle Press books (if you REALLY want to LEARN, that is?)

We have a great deal of sympathy with Mr. Burton's original argument. While Oracle may be large and sophisticated, there are many larger, more sophisticated and more complicated software systems that are sufficiently well documented that it is not necessary to hire a consultant who knows what is necessary to operate the software.

I believe a worth conclusion one may draw from Mr. Burton's original message is that it is wasteful and pointless to deliver such a system. Were we to produce software so ill-documented, such unprofessional products would send us out of business. On the other hand, Oracle has a bit of a lock on this part of the market (after all, we do use the database -- and so do you), so Oracle need not document it well.

While some might commend Mr. Phelan for his tenacity in pursuit of Oracle details, that is exactly what we do not seek. The company for which I work does not (nor does it want to) make money by knowing the intricacies of a particular database. Instead, we make a product which uses a database as a tool for storing information; the less that gets in the way of effectively doing so, the better. Smarter documentation would be one way for us to achieve that. The sorry state of Oracle's documentation is an impedement.

> Your one months experience of Oracle on your own with just the Oracle
> Documentation CD ROM and no hardcopy manuals IS NOT ENOUGH ALONE for you
> to be undertaking what you seem to be undertaking, an 'award winning
> software developer' (your words, not mine) or not.
>
> Now, which bit didn't you understand?

Regretfully, Mr. Phelan is absolutely correct. The point not addressed in his message was that the situation of such poor documentation need not be so. While he may find himself well employed by having expertise and knowledge of such a system, it is maddening that novice users not be able to better use the software. More typical of well-documented software is the case that experienced users can use a system better -- not that the first-time user cannot use it at all.

Mr. Burton gave several such examples of documentation pitfalls for novice users. He is not alone in problems encountered, even for experienced users. On an installation of Oracle for NT in spring, we noted more than 40 errors in the manual of the installation process (we would not have overcome them except for experience with Oracle on three flavors of Unix); while we sent a detailed accounting of them to the Oracle address asking for comment, we heard nothing in reply and expect that we never will. This kind of list can go on endlessly: consider the many internal "cheat sheets" that Oracle support uses themselves and has had to fax to us when we got into a well-known abyss of non-documentation -- why not just provide that sort of information with the shipped product? The problem in those circumstances was not that the software is large and sophisticated; the necessary material was simply absent.

While information on database server installation and setup is lacking, the documentation on Designer/2000 product is almost conspiratorally poor. What a pity: the tiny document describing the tutorial was wonderful! It is the full documentation that was missing. Again, we agree with Mr. Burton that the Oracle Press books are incomplete and lacking in examples; the "Complete Reference" is complete (and useful) only if one already knows the material. We often find them distracted, not to the point.

As we work with Sybase, Informix, and Oracle and four different operating systems, we have experience with a great many styles and sources of documentation. Of all the manuals in our library, Oracle easily comes up short. While Oracle is popular software, we do not recommend it (in fact, disparage it) precisely because the documentation.

Regretfully, this deficit makes professional database software seem another candidate for takeover by the Evil Empire. While we hate giving them money, we expect that SQL Server -- with its marketing force, ease of use and simpler explanation -- will take over an unexpected part of the traditional database market for small and medium commercial users.

True, it is possible for new users to gain the expertise we have gained in Oracle over many years. But why would a new user need to bother to do so -- except for the next couple of years when Oracle is still ahead?

John Cierra Received on Wed Jul 09 1997 - 00:00:00 CDT