Suggestion for the docs to make them useful for experts and newbies alike, without having to separate them out according to level:
What I really like about the MySQL docs* is that it's arranged the same all the way throughout:
1) A quick, full syntax of the command, with options included where they should be and marked as optional, e.g. the SELECT Syntax.
2) And then there's a complete, in-depth explanations of what every single piece of that statement means and how it's used.
Having the full syntax at the top makes a great refresher for experts who just need to learn the site-specific syntax or double-check an option they don't use often, and the complete, in-depth explanations in plain English are useful for beginners just starting out.
Also, "official" cookbook examples should be linked on the doc pages that explain the syntax.
* The newer versions seem to be getting more gobbledygooky and less like they used to be, but they're still a decent enough example for useful documentation. (The Django docs, OTOH, are an example for how not to write useful docs. *rolls eyes*)
no subject
What I really like about the MySQL docs* is that it's arranged the same all the way throughout:
1) A quick, full syntax of the command, with options included where they should be and marked as optional, e.g. the SELECT Syntax.
2) And then there's a complete, in-depth explanations of what every single piece of that statement means and how it's used.
Having the full syntax at the top makes a great refresher for experts who just need to learn the site-specific syntax or double-check an option they don't use often, and the complete, in-depth explanations in plain English are useful for beginners just starting out.
Also, "official" cookbook examples should be linked on the doc pages that explain the syntax.
* The newer versions seem to be getting more gobbledygooky and less like they used to be, but they're still a decent enough example for useful documentation. (The Django docs, OTOH, are an example for how not to write useful docs. *rolls eyes*)