Oracle Documents

I’ve run into a nice post about RTFM on the BAAG journal. Yes, I know this is not exactly news, but I think its going to resonate with many DBAs. However, I suspect that the RTFM post oversimplifies what is actually a rather painful issue.

Lets start with the fact that many DBAs are not native English speakers. They know enough English to get along nicely, but reading technical documents can still be a slow and painful activity. Perhaps slower than waiting for a kind soul on a mailing list.

Then, there is the fact that getting meaningful answers out of Oracle documentation is a bit of an art form. There are both OTN documents and documents in Metalink. They sometimes contradict, so you need to verify which is more updated, but make sure it matches your version.

If you need to know how to configure automatic memory manager or how to rebuild an index, the documentation is pretty good. If you need to know what happens when you set SGA_MAX_SIZE to zero while using automatic memory management, you are in for a significant search at the end of which you will have more information and still end up having to make a guess which may or may not be correct. I remember looking for a good quote that will allow me to prove to my boss that if we rebuild an index with parallel option, all queries using this index will be parallelized to the same degree. I couldn’t find one, although it could be inferred by combining several paragraphs from two different books in the right way.

There is a reason for the huge market for Oracle books other than the official documentation. Thats because the official documentation is difficult to read and sometimes is not even good enough as a reference. There are a bunch of websites, blogs and magazine articles that explain information that is already contained in Oracle documents. A co-worker is learning PL/SQL and asked for good book. You can bet I told him to get Steve Feuerstein’s PL/SQL book and didn’t tell him to download Oracle’s book from OTN.

So, I agree with Simon Haslam at BAAG that people need to RTFM. I just wouldn’t recommend Oracle’s official documentation for that purpose.

2 Comments on “Oracle Documents”

  1. Gints Plivna says:

    I’m non native english speaker but haven’t any trouble reading technical docs. To be frank I have problems reading Shakespeare though 😉 AFAIK even native english speakers do 🙂 So if one is planning to be a DBA, or even to be in IT industry as such, not knowing english isn’t any excuse, at least to my mind.
    Speaking about Oracle docs and your example about PL/SQL newbie – cannot find any reason why not to recommend PL/SQL user’s guide and reference. It is free, it has many examples, it has many valid guidelines, of course probably it has some guidelines that at least are discussible, but I think the overall quality of Oracle docs is quite good. Just the hardest thing probably is to scan them through and understand what each of them (or better let’s say most popular of them, because I’ve never scanned all more than 400 docs 😉 contains.

  2. prodlife says:

    I know few DBAs who have trouble with technical docs due to English problems, they can read the docs eventually, but they find it difficult enough that they try to avoid it. Its horrible that they work as DBAs, but they exist and we run into them on forums and mailing lists.

    Regarding the PL/SQL book – Oracle’s book is entire valid, contains all the correct information and even few nice examples. It is just that Feuerstein’s book is much better. He is simply doing a better job explaining the ideas and the examples are located correctly (I think Oracle places all examples at the end of each chapter). It is probably a matter of taste, but I got a much better understanding about PL/SQL after reading Feuerstein’s book.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s