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.

4 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;

Unknown 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!

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

Unknown said...

Hello from future. Oracle docs suck here as well, be it Java or SQL. They suck as hard as Git.

command [optional_gubbrish] argument --brain_fck=[YES|ALWAYS|MORE DEFAULT:=ALWAYS]

I always do keyword -site:oracle.com because oracle docs are worse than useless.

No, oyu cannot go through their tutorials. I tried PL/SQL on Lynda.com and only found
select * from table where my_id=34 and pos_number=69 Now you are an expert on PL/SQL

Consider a Python function returning a tuple.

def max_min(v):
a,b = /* select var1,var2 from some_table where obj_id = v */
return a > b ? a : b , a > b ? b : a

x,y = max_min(17)

Now try to write the same an sql function, don't use min and max.