justinmclean commented on code in PR #5840:
URL: https://github.com/apache/gravitino/pull/5840#discussion_r1881187011
##########
docs/cli.md:
##########
@@ -64,54 +68,60 @@ The general structure for running commands with the
Gravitino CLI is `gcli entit
-x,--index display index information
-z,--provider <arg> provider one of hadoop, hive, mysql, postgres,
iceberg, kafka
- ```
+```
-## Commands
+## Commands Types
The following commands are used for entity management:
-- list: List available entities
-- details: Show detailed information about an entity
-- create: Create a new entity
-- delete: Delete an existing entity
-- update: Update an existing entity
-- set: Set a property on an entity
-- remove: Remove a property from an entity
-- properties: Display an entities properties
+- `create`: Create a new entity
+- `delete`: Delete an existing entity
+- `details`: Show detailed information about an entity
+- `list`: List available entities
+- `properties`: Display an entity's properties
+- `remove`: Remove a property from an entity
+- `set`: Set a property on an entity
+- `update`: Update an existing entity
Review Comment:
While there may be other logical ways to order them, that doesn't mean we
should do it alphabetically. `list` is first as it is most likely the first
command a user will want to use, followed by `details` the next most likely
command a user would use and `list` and `details` are commonly used together.
`delete` pairs with `create` so that is why it comes before `update`. If the
commands were slightly different, I'd would have gone with a more CRUD style
ordering.
As a native English speaker, I would not expect this to be in alphabetical
order. Alphabetical order is used when you have a long list. If there were, say
20 options, I would sort them alphabetically or break them up into groups. Not
in the `--help` command is sorted alphabetically, but I had considered
following this advice from https://clig.dev/#help
"Display the most common flags and commands at the start of the help text.
It’s fine to have lots of flags, but if you’ve got some really common ones,
display them first. For example, the Git command displays the commands for
getting started and the most commonly used subcommands first:"
There is also actual usability research on this:
https://www.nngroup.com/articles/alphabetical-sorting-must-mostly-die/
Basically, when users don't know the name of the thing they want, it makes
A–Z listings useless and A–Z listings are directly harmful because they hide
logical ordering.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
