Friday, March 7, 2008

Oracle documentation sucks

Warning, rant below:

I'm trying to learn how to work with XML in PL/SQL. So, I need some examples and reference manual. For C# or WINAPI I'm used to search for method names on google and usually I get link to MSDN. There is detailed explanation about method, parameters, types, usual and special values. There is often example of usage.

That's not true for Oracle documentation. Look at this . Procedure doesn't have it's own page, name of link is cryptic, so google has small chance. The documentation is poor, missing hyper-links to types of procedure parameters. This is documentation given by Oracle programmers, not by documentation writer.

There are zilions of users of Oracle database struggling with basics, just because of bad documentation. If you are searching for solution to your question, you usually find some discussion group with bad example of usage from some other confused user and below some non-authoritative response from people repeating same answers twenty times a day.

Another problem is that there is no documentation standard for in code documentation of PL/SQL. There are some open-source tools which are trying to map for example javadoc tags to procedures, but nobody knows about that.

I hope I missed something and someone will tell me where are standards described and who is evangelizing about it. Someone will give me link to real reference documentation to Oracle built-in packages.

3 comments:

Mormegil said...

Not that MSDN is _always_ the perfect one. Especially the examples are often similar to something like:

// set the property to true
myClass.SomeProperty = true;

Chris said...

One of the first Oracle documents I ever had the (ahem) pleasure of reading started:

There are three ways to do x:

1) adfasdf adsf
2) adf af asdf
3) asdf asd asdf
4) asdf a sf as asdf

I knew I was in trouble!

Eugene Shults said...

Agreed. Learned and became certified in MSSQL via MSDN articles, which are not perfect, but good enough.

Oracle on the other hand? My God...it's almost as if they want you to spend thousands and thousands of dollars to take their training classes to obtain information that could easily be better documented.

I support a mixed environment, and Oracle is BY FAR the most painful environment to support. The simplest matters are a headache.

I'm convinced MSSQL is a better tech, despite what the snobs may say..