[Maria-docs] Please use "syntax, example, text, standards conformity" as format for reference manual type of pages
Hi Daniel
I was reading http://kb.askmonty.org/v/virtual-columns
...compare the ordering of the storyline to http://dev.mysql.com/doc/refman/5.1/en/create-table.html
The one from MySQL manual works great for me: syntax first (this is what I most commonly need) basic example(s) second (usually need this too for complex syntax) more indepth text, exceptions, etc... come third
Also, I propose we adopt the practice from the PostgreSQL manual of always including last a section on which standards the feature conforms to (or if it is MySQL specific, or MariaDB specific feature, state that).
Just some tips from an avid reader! henrik
On Thu, 21 Oct 2010 20:48:11 +0300 Henrik Ingo henrik.ingo@avoinelama.fi wrote:
Henrik> Hi Daniel Henrik> Henrik> I was reading Henrik> http://kb.askmonty.org/v/virtual-columns Henrik> Henrik> ...compare the ordering of the storyline to Henrik> http://dev.mysql.com/doc/refman/5.1/en/create-table.html Henrik> Henrik> The one from MySQL manual works great for me: Henrik> syntax first (this is what I most commonly need) Henrik> basic example(s) second (usually need this too for complex Henrik> syntax) more indepth text, exceptions, etc... come third
Actually, the order that most KB pages follow is:
* Syntax * Description * Example(s)
The virtual columns page is kind of an aberration in that it has the description first, then syntax, then examples.
The reason for putting examples last is because some of the examples can get quite long (especially if they need explaining), so putting them at the bottom is better.
Assuming the above order is fine with you, I'll update the VC page to follow it.
Henrik> Also, I propose we adopt the practice from the PostgreSQL Henrik> manual of always including last a section on which standards Henrik> the feature conforms to (or if it is MySQL specific, or MariaDB Henrik> specific feature, state that).
Sure, that would be a good thing to add. But like many good ideas, the devil is in the details.
Knowing whether an item is MySQL or MariaDB specific is pretty easy.
Stating whether a feature is standards compliant sounds quite a bit harder since I'm not an expert on the SQL standard. I know there are people out there who can simply look at, for example, the MariaDB ALTER TABLE syntax definition and state "yes, this conforms to SQL standard version XX" (or whatever), but I'm not one of those people. :) Do you know if there is anything existing that we can use that has this standards compliance information already?
Thanks.
On Fri, Oct 22, 2010 at 3:49 PM, Daniel Bartholomew dbart@askmonty.org wrote:
Actually, the order that most KB pages follow is:
* Syntax * Description * Example(s)
The virtual columns page is kind of an aberration in that it has the description first, then syntax, then examples.
The reason for putting examples last is because some of the examples can get quite long (especially if they need explaining), so putting them at the bottom is better.
Yes. So to put what I said in another way, at the start of the description, I'd like to see a basic example showing the most common usage :-)
Henrik> Also, I propose we adopt the practice from the PostgreSQL Henrik> manual of always including last a section on which standards Henrik> the feature conforms to (or if it is MySQL specific, or MariaDB Henrik> specific feature, state that).
Sure, that would be a good thing to add. But like many good ideas, the devil is in the details.
Knowing whether an item is MySQL or MariaDB specific is pretty easy.
Stating whether a feature is standards compliant sounds quite a bit harder since I'm not an expert on the SQL standard. I know there are people out there who can simply look at, for example, the MariaDB ALTER TABLE syntax definition and state "yes, this conforms to SQL standard version XX" (or whatever), but I'm not one of those people. :) Do you know if there is anything existing that we can use that has this standards compliance information already?
Officially it isn't publicly available, but googling for it... http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt
However, to know what is fro SQL-92, SQL-99 etc... is difficult, I surely don't.
...in practice the easiest thing to do is to look at the PostgreSQL manual. That will get us pretty far already.
(I see the beginning of a documentation howto :-)
henrik
participants (2)
-
Daniel Bartholomew -
Henrik Ingo