the bear called documentation

Working with Oracle products over the last several months, the thing that struck me most apart from the often-appealing/sometimes-daunting configurability/complexity is the complete and utter sloppiness of documentation. The hands-on labs have errors: grammatical, syntactical. The sample code has versioning errors. In the rush to churn out releases distinguished only by a third- or fourth- order decimal digit, the corporate whose database I most admire (and which is, ironically, their only in-house product: the J2EE container and the application server came from Orion; TopLink came from WebGain; JDeveloper came from JBuilder) has decided to spend little to no time in patiently providing useful accompanying guides and documentation. Finding documentation for the version you are dealing with is often an ordeal on the OTN (that's Oracle Technology Network aka Oracle Technet for people who do not 'worship' the oracle). URLs mentioned in online guides and books published under the auspices of the Oracle Press (a collab with Osbourne Books) go stale as you read the book. The search facilities are rather primitive. And the only companion one has is good ol' Google.

But, you say, I have the release number for the reference guide. That should make my search easier. Think again. Often the old documents are found only on old mirrors or on sites maintained by kind souls for previous versions. Otherwise, you're out of luck.

Case in point: Working with JDeveloper's wizard-based CMR/CMP based on tables with composite primary keys and referential integrity, I was rewarded with the 'self-explanatory' NullPointerException followed by a 'helpful' exception stack trace when I attempted to test the application that JDeveloper put together for me. This 'by my own betrayed' self-destructive software quirk is something I have seen before in Microsoft products. In its hot competition with Microsoft, Oracle probably decided to match the software behavioural aspects as well. Back to my problem though. My searches for useful tips and suggestions came to naught. A colleague finally unearthed a HOWTO addressing this exact issue -- under the pages devoted to a technology preview of a newer version of the J2EE container. Makes sense right? And the tips are germane even to this current version that we're using. And as we test the recommendations made in the HOWTO to rectify the problem, my eyes scan the page that lists all the new HOWTOS and stop at the following sentence, which is in full keeping with the documentation staleness/version chaos problem (my colouring emphasis added):
For example Oracle9iAS Containers for J2EE (9.0.2) does not support some aspects of the EJB 2.0 specification, so the Local Interfaces How-To will not work on version 9.0.3.