Bug #1283 Manual's installation chapter confusing, poorly organized
Submitted: 15 Sep 2003 14:19 Modified: 10 Dec 2003 18:12
Reporter: [ name withheld ] Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:4.0.15 OS:N/A
Assigned to: Bugs System CPU Architecture:Any

[15 Sep 2003 14:19] [ name withheld ]
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.
[10 Dec 2003 18:12] Arjen Lentz
Thank you for your bug report. This issue has been addressed in the
documentation. The updated documentation will appear on our website
shortly, and will be included in the next release of the relevant
product(s).

Additional info:

The installation chapter is in the process of being overhauled, and your comments are most useful. Thanks for your detailed feedback!