Re: Documentation for this(Java) connector is poorly written
Posted by:
kumbamamfe
Date: September 06, 2005 05:55AM
> If you are already experienced with using JDBC, you might consider
> starting with the section "Installing Connector/J".
OK, Mark. Let's move then straight to the installing! Here is the chapter,
in all its glory:
> MySQL Connector/J is distributed as a .zip or .tar.gz archive containing the
> sources, the class files a class-file only "binary" .jar archive named
> "mysql-connector-java-[version]-bin.jar", and starting with
> Connector/J 3.1.8 a "debug" build of the driver in a file named
> "mysql-connector-java-[version]-bin-g.jar".
> Starting with Connector/J 3.1.9, we don't ship the .class files "unbundled",
> they are only available in the JAR archives that ship with the driver.
> You should not use the "debug" build of the driver unless instructed do
> do so when reporting a problem or bug to MySQL AB, as it is not designed
> to be run in production environments, and will have adverse performance
> impact when used. The debug binary also depends on the Aspect/J runtime
> library, which is located in the src/lib/aspectjrt.jar file that comes
> with the Connector/J distribution.
> You will need to use the appropriate gui or command-line utility to
> un-archive the distribution (for example, WinZip for the .zip archive,
> and "tar" for the .tar.gz archive). Because there are potentially long
> filenames in the distribution, we use the GNU tar archive format. You
> will need to use GNU tar (or an application that understands the GNU tar
> archive format) to unpack the .tar.gz variant of the distribution.
> Once you have extracted the distribution archive, you can install the driver
> by placing mysql-connector-java-[version]-bin.jar in your classpath, either
> by adding the FULL path to it to your CLASSPATH enviornment variable, or by
> directly specifying it with the commandline switch -cp when starting your JVM
> If you are going to use the driver with the JDBC DriverManager, you would
> use "com.mysql.jdbc.Driver" as the class that implements java.sql.Driver.
What you download is a zip file, so the actual installation instructions
start at the fourth paragraph! The first three paragraphs, way more than
a hundred words, are simply standing in the way of the action. The worst
culprit is the second paragraph, "Starting with Connector/J 3.1.9, we don't ship
the .class files "unbundled", they are only available in the JAR archives bla,
bla, bla". That can wait! In fact if you remove it altogether, no one will notice.
My key point is this. The business at hand is to guide the user to install a
program and to follow through until the user can get the program to run.
Any other business, whether it be JDBC, JAVA or how bundled files ship,
has to wait. This is internet. Why doesn't the writer use links to include,
on a separate page, all the extraneous information?