Re: [Maria-docs] undocumented features?
Hi all!
I have a request: could you please check that all current/future features are documented in the proper KB page? The request includes "sub-features", that is, syntaxes that were implemented as part of a more generic feature. It is very
Hi Ian Please don't take this as an accuse. I understand that keeping documentation and links updated requires a great effort. Generally you are doing a great work, and it wouldn't be reasonable to expect a flawless documentation. But I still think that I found an undocumented feature. You confirm that probably there are other cases, and I think this is a problem that should be fixed somehow. Let me explain better my point of view. A statement documentation page is expected to include the complete syntax, so if I look at GRANT page and don't find a privilege, that privilege doesn't exist for me. Mentioning the feature in another page, and without any details, is not enough. Also note that HELP has the same problem. I think that most users don't know that HELP contents refer to MySQL (and the KB lacks this info). In my opinion, if you cannot fill the help tables with MariaDB-specific information, you should return a warning every time a user runs HELP command. Bye, Federico -------------------------------------------- Gio 11/8/16, Ian Gilfillan <ian@mariadb.org> ha scritto: Oggetto: Re: [Maria-docs] undocumented features? A: maria-docs@lists.launchpad.net Data: Giovedì 11 agosto 2016, 17:10 Hi Federico I know one of the weaknesses has been adding new content as a new article, and then not cross-linking it on all related pages, so you're right that this is probably not the only case. It'll be quite hard to 'check that all ... features are documented in the proper KB page' though! If I do spot anything will be sure to add it, otherwise feel free to add/report if you spot something. Thanks for adding the missing content in this case. On 11/08/2016 10:36, Federico Razzoli wrote: possible that there are undocumented things, in my opinion.
For
https://mariadb.com/kb/en/mariadb/aborting-statements/
However the GRANT
example, I just documented GRANT ... MAX_STATENENT_TIME. I learned it exists because I've read this page: page didn't mention that syntax until I added that content. This means that, even if a user reads the documentation, he hardly knows about this feature. Also, I needed to experiment: in fact, from the above page, it wasn't clear if MAX_STATEMENT_TIME was a permission or a user resourse limit.
Again, this is just a request, not
criticism. I'm writing this mail because, in my opinion, we all would benefit from all features being documented.
Thank you for your
great work, MariaDB!
Regards
Federico _______________________________________________ Mailing list: https://launchpad.net/~maria-docs Post to : maria-docs@lists.launchpad.net Unsubscribe : https://launchpad.net/~maria-docs More help : https://help.launchpad.net/ListHelp
It's a good idea to issue a warning about the HELP output, as https://jira.mariadb.org/browse/MDEV-6521 is probably not going to get fixed soon. That should be much easier than actually trying to generate output from the KB. On 11/08/2016 23:00, Federico Razzoli wrote:
Hi Ian
Please don't take this as an accuse. I understand that keeping documentation and links updated requires a great effort. Generally you are doing a great work, and it wouldn't be reasonable to expect a flawless documentation. But I still think that I found an undocumented feature. You confirm that probably there are other cases, and I think this is a problem that should be fixed somehow. Let me explain better my point of view.
A statement documentation page is expected to include the complete syntax, so if I look at GRANT page and don't find a privilege, that privilege doesn't exist for me. Mentioning the feature in another page, and without any details, is not enough.
Also note that HELP has the same problem. I think that most users don't know that HELP contents refer to MySQL (and the KB lacks this info). In my opinion, if you cannot fill the help tables with MariaDB-specific information, you should return a warning every time a user runs HELP command.
Bye, Federico
-------------------------------------------- Gio 11/8/16, Ian Gilfillan <ian@mariadb.org> ha scritto:
Oggetto: Re: [Maria-docs] undocumented features? A: maria-docs@lists.launchpad.net Data: Giovedì 11 agosto 2016, 17:10
Hi Federico
I know one of the weaknesses has been adding new content as a new article, and then not cross-linking it on all related pages, so you're right that this is probably not the only case. It'll be quite hard to 'check that all ... features are documented in the proper KB page' though! If I do spot anything will be sure to add it, otherwise feel free to add/report if you spot something.
Thanks for adding the missing content in this case.
Hi all!
I have a request: could you please check that all current/future features are documented in the proper KB page? The request includes "sub-features", that is, syntaxes that were implemented as part of a more generic feature. It is very
On 11/08/2016 10:36, Federico Razzoli wrote: possible that there are undocumented things, in my opinion.
For
https://mariadb.com/kb/en/mariadb/aborting-statements/
However the GRANT
example, I just documented GRANT ... MAX_STATENENT_TIME. I learned it exists because I've read this page: page didn't mention that syntax until I added that content. This means that, even if a user reads the documentation, he hardly knows about this feature. Also, I needed to experiment: in fact, from the above page, it wasn't clear if MAX_STATEMENT_TIME was a permission or a user resourse limit.
Again, this is just a request, not
criticism. I'm writing this mail because, in my opinion, we all would benefit from all features being documented.
Thank you for your
great work, MariaDB!
Regards
Federico
participants (2)
-
Federico Razzoli -
Ian Gilfillan