Thursday, October 16, 2003

the standards of commercial documentation

I've been playing around with version 9.0.3 of TopLink, a commercial O/R mapping persistence tool sold by Oracle (a licensing cost of about $7,000 per processor). Oracle bought TopLink from WebGain
(see also: origins of WebGain). Oracle currently (release 2 aka 9.0.2 or 9.0.3 -- the confusion somehow translates into more sales!) ships TopLink as a separate CD in the Oracle9iAS pack (the new 10g promises integration of TopLink into both Oracle9iAS and JDeveloper). I've been having a mixed experience with the Oracle Suite of Acquired Products (Oracle9iAS, JDeveloper, TopLink), and although my little test application using the developer preview of JDeveloper 10g (aka formerly ka 9.0.4), the first to provide some level of integration with the TopLink Mapping Workbench was a minor success (the strange documentation notwithstanding), I hit a small roadblock and went after the Javadocs for TopLink. Lo and behold! Bad javadocs. The page in question describes the XMLProjectReader class. Note how the parameters described do not match the method signatures. Given that there are so many fairly mature tools to automate most of the process of creating and compiling javadocs, I don't really understand how this can happen. Did this ship straight from WebGain and get shipped out again without as much as a cursory glance? I'm itching for the day when I can test the persistence frameworks in the public domain like Hibernate and implementations of JDO. Any $$$ saved in the process can compensate for any "extra" hours of learning with the lack of documentation (which is the same as learning with the overabundance of useless documentation). And any $$$ saved after all that can be safely donated to these worthy causes. No valid arguments for commercial bloatware come to mind. In the meantime, suffer in silence while the higher-ups dish out the dead presidents. Sigh!

No comments:

Creative Commons License
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.