Bug #16789 Documentation enhancement
Submitted: 25 Jan 2006 18:30 Modified: 27 Jul 2006 20:28
Reporter: Dave Silvia Email Updates:
Status: Won't fix Impact on me:
Category:MySQL Server: Documentation Severity:S4 (Feature request)
Version: OS:
Assigned to: Paul Dubois CPU Architecture:Any
Triage: D4 (Minor)

[25 Jan 2006 18:30] Dave Silvia
Admittedly, it's been some time since I've looked at such documentation, but I believe at one time SQL documentation included sections on clauses (e.g. WHERE) that isolated specifics for that part of the language.

I've not found any such correlative in MySQL documentation.  If I need to know something about a WHERE clause, I must laboriously search for all instances of 'WHERE' in the document.  This is such a gargantuan task in the HTML help versions, which do not allow any specification excepting the character sequence "'w''h''e''r''e'", both case insensitive and in any context (i.e., can be within another word like 'everywhere'), that this source is not even a viable candidate.  In the pdf version, the task is less onerous, but still of daunting size (MySQL-4.1-en.pdf, for example, returns 525 results for exact word, all caps 'WHERE').

Could there not be a separate section, as in for 'SELECT' or 'INSERT', which describes the generics of a WHERE clause (or 'VALUES', or 'INTO', etc.)  This would make the life of the casual user much more pleasant, and, as a byproduct, increase your user base by luring in more casual users who may now be put off by the necessity of needing to have a great deal of 'pre-knowledge' of SQL to use the current documentation.

Dave S.

How to repeat:

Suggested fix:
Make the documentation more user friendly.  Not just a codex for the SQL initiated.
[30 May 2006 22:11] Valeriy Kravchuk
Thank you for a reasonable documentation request.
[26 Jul 2006 23:30] Paul Dubois
This is a reasonable request, but not for the MySQL Reference
Manual, which isn't a tutorial. I suggest instead that you take a
look at one of the more tutorial-oriented MySQL books or articles
that are available. See, for example:

[27 Jul 2006 20:28] Dave Silvia
I guess I'm having a bit of trouble understanding why adding sections to describe syntactically how to use WHERE (and others like VALUES or INTO) constitutes a tutorial whereas a syntax for SELECT and INSERT does not make a tutorial(???).  I'm not suggesting detailed examples, just a straightforward way to locate WHERE (and the like) within the MySQL Reference Manual.  The information is there, it's just not tagged like SELECT or INSERT so that it can be easily found.  I believe that WHERE (VALUES, INTO, etc.) are basic enough (as are SELECT and INSERT) to warrant an easy way to find their syntax within the Reference Manual.  I feel that "Won't fix" is a bit arbitrary.  Couldn't you rethink this?