-
Notifications
You must be signed in to change notification settings - Fork 473
Description
A user on our forum tried to use the full grammar to understand GRANT
and privileges can called out that that grammar isn't the best resource for new users to learn such details. We intend the statement-specific pages to be the entry point for users, so we should add a tip at the top of the full grammar pointing users to those pages.
From this forum post:
What are some areas where CockroachDB was hard to use?
I know there's some pride in the auto-documentation of SQL using grammar diagrams, but I find the flow-chart style diagrams more confusing than actual real-world examples. Especially when it comes down to having to follow links several times to see what is a valid input for a particular command. For instance, if I want to see what privileges I can grant to a user, I first go to the grant_stmt documentation, then need to follow the privileges link, which contains part of the potential privilege options (ALL), otherwise I need to drill down into privilege_list, which is itself a (from a user persective) useless section, only used to get to privilege, which has the rest of the privileges I may want to grant someone.
GRANT isn't meant to be a specific pain point, but rather just to illustrate the types documentation rabbit holes I've found myself digging through.