Description:
In the MySQL Reference Manual, the installation chapter (section 2) is quite
confusing because parts are poorly organized.
One main problem is that it's not clear which sets of instructions are
alternatives, and which need to be followed in sequence.
* If the user starts with section 2.1.1, Installing MySQL on Windows,
it's not clear whether section 2.4, Post-installation Setup and Testing,
needs to be followed (or whether because 2.1 is "Quick Standard
Installation...", essential post-installation setup already done).
* Section 2.4 says:
Once you've installed MySQL (from either a binary or source distribution),
you need to initialise the grant tables...
and says to run:
shell> ./scripts/mysql_install_db
However, if you installed the Windows binary distribution per section
2.1.1 Installing MySQL on Windows, the instructions supposedly apply
(per the wording "from...a binary...distribution") but tell you to run
a Unix shell script on Windows.
That is, it's not clear when section 2.4 applies (and, if it applies,
the instructions aren't correct).
* Section 2.1.1.1, Installing the Binaries, says:
7. Finish the install process.
and the is followed by section 2.1.1.2, Preparing the Windows MySQL
Environment.
However, it isn't clear whether "finish the install process" just means
to finish the installer and proceed to section 2.1.1.2, or whether it
means to perform other steps documented later (e.g., section 2.4).
Other text is unclear because of the order in which things appear:
* Section 2.1.1.2, Preparing the Windows MySQL Environment, says you can
choose different server versions, but doesn't say how (where) you choose
them.
* Section 2.1.1.2 mentions the need for an options file, but then goes off
into describing default file locations, confusingly leaving the user
hanging regarding how to create an options file.
(Yes, it does get back to the options file eventually, but it's confusing
in the current order.)
* Section 2.1.1.2 should probably mention options files first in the
section.
* Section 2.1.1.2 says:
You will find it helpful to use an option file...under the following
circumstances:
* The installation or data directories are different from the default
locations (`C:\mysql' and `C:\mysql\data').
* You need to tune the server settings. ...
but then seems to go too far on a tangent about setting up InnoDB
transactional tables. (The tangent distracts from the current subject
of the option file.)
Other:
* (The recommendation to set the MySQL root user's password appears only in
the Mac section (2.1.3).)
* Section 2.1.1.2 is titled "Preparing the Windows MySQL Environment."
It's unclear whether "prepare":
- refers to post-installation setup (and is the quick version of section
2.4, Post-installation Setup and Testing for the installation type
covered by 2.1.1), or
- refers to preparing before installing.
How to repeat:
Um...this a documentation bug report. Why does this bug report page insist
that I "supply instructions on how the bug [I] [am] reporting can be repeated"?
Suggested fix:
* If following the instructions in section 2.1, Quick Standard Installation of
MySQL, means that section 2.4, Post-installation Setup and Testing, doesn't
need to be followed, something in section 2.1 (or 2.1.x) should mention that.
* If section 2.4 does not apply for releases installed per Quick Standard
Installation of MySQL, section 2.4 should say so.
* In section 2.1.1.2, Preparing the Windows MySQL Environment, clarify
whether "preparing" refers to preparing to install or to preparing the
system after installation (settting it up).
* Review the installation chapter from the points of view of users installing
from different distribution types. Make sure each user can tell which parts
of the text apply for that user's installation case.