From 617c704fde34452f753cafa22b27395d6828b217 Mon Sep 17 00:00:00 2001 From: Jeremy Hoover Date: Sun, 4 Jan 2026 10:08:43 +0200 Subject: [PATCH 1/2] docs: Improve help text clarity and consistency across all commands - Updated core command descriptions for clarity and conciseness - Standardized terminology across all command groups - Improved auth commands: 'authenticate' instead of 'log in' - Simplified config commands with user-friendly language - Enhanced ACL commands with consistent formatting - Clarified job commands with 'asynchronously'/'synchronously' - Updated label commands to be more specific - Improved table commands with clearer actions - Updated command description constants in fab_constant.py - Applied UX writing best practices throughout Changes implement recommendations from UX writing analysis --- .changes/unreleased/docs-20260104-100757.yaml | 3 ++ src/fabric_cli/core/fab_constant.py | 38 +++++++++---------- src/fabric_cli/parsers/fab_acls_parser.py | 8 ++-- src/fabric_cli/parsers/fab_auth_parser.py | 6 +-- src/fabric_cli/parsers/fab_config_parser.py | 6 +-- src/fabric_cli/parsers/fab_jobs_parser.py | 12 +++--- src/fabric_cli/parsers/fab_labels_parser.py | 6 +-- src/fabric_cli/parsers/fab_tables_parser.py | 6 +-- src/fabric_cli/utils/fab_commands.py | 16 ++++---- 9 files changed, 51 insertions(+), 50 deletions(-) create mode 100644 .changes/unreleased/docs-20260104-100757.yaml diff --git a/.changes/unreleased/docs-20260104-100757.yaml b/.changes/unreleased/docs-20260104-100757.yaml new file mode 100644 index 00000000..cde1661b --- /dev/null +++ b/.changes/unreleased/docs-20260104-100757.yaml @@ -0,0 +1,3 @@ +kind: docs +body: Improve help text clarity and consistency across all commands with concise descriptions, consistent terminology, and user-focused language +time: 2026-01-04T10:07:57.3138333Z diff --git a/src/fabric_cli/core/fab_constant.py b/src/fabric_cli/core/fab_constant.py index 2e21356b..712ed0fa 100644 --- a/src/fabric_cli/core/fab_constant.py +++ b/src/fabric_cli/core/fab_constant.py @@ -130,23 +130,23 @@ } # Command descriptions -COMMAND_AUTH_DESCRIPTION = "Authenticate fab with Fabric." -COMMAND_AUTH_STATUS_DESCRIPTION = "Display active account and authentication state." +COMMAND_AUTH_DESCRIPTION = "Authenticate with Fabric." +COMMAND_AUTH_STATUS_DESCRIPTION = "Show authentication status." COMMAND_FS_DESCRIPTION = "Workspace, item and file system operations." -COMMAND_JOBS_DESCRIPTION = "Manage tasks and jobs." -COMMAND_TABLES_DESCRIPTION = "Manage tables." +COMMAND_JOBS_DESCRIPTION = "Manage and schedule jobs." +COMMAND_TABLES_DESCRIPTION = "Manage Delta tables." COMMAND_SHORTCUTS_DESCRIPTION = "Manage shorcuts." -COMMAND_ACLS_DESCRIPTION = "Manage permissions [admin]." +COMMAND_ACLS_DESCRIPTION = "Manage access control lists [admin]." COMMAND_ACLS_LS_DESCRIPTION = ( - "List ACLs for a workspace, item, gateway, connection or OneLake." + "List ACLs for a workspace, item, gateway, connection or OneLake resource." ) -COMMAND_ACLS_RM_DESCRIPTION = "Remove an ACL from a workspace, gateway or connection." +COMMAND_ACLS_RM_DESCRIPTION = "Remove an ACL from a workspace, gateway, or connection." COMMAND_ACLS_GET_DESCRIPTION = ( - "Get ACL details for a workspace, item, gateway, connection or OneLake." + "Get ACL details for a workspace, item, gateway, connection or OneLake resource." ) -COMMAND_ACLS_SET_DESCRIPTION = "Set ACL on workspace, gateway or connection." -COMMAND_CONFIG_DESCRIPTION = "Manage configuration settings." -COMMAND_API_DESCRIPTION = "Make an authenticated API request." +COMMAND_ACLS_SET_DESCRIPTION = "Set ACLs on a workspace, gateway, or connection." +COMMAND_CONFIG_DESCRIPTION = "Manage CLI configuration." +COMMAND_API_DESCRIPTION = "Make authenticated API requests." COMMAND_EXTENSIONS_DESCRIPTION = "Manage extensions." COMMAND_LABELS_DESCRIPTION = "Manage sensitivity labels [admin]." COMMAND_CAPACITIES_DESCRIPTION = "(tenant) Manage capacities [admin]." @@ -163,7 +163,7 @@ ) COMMAND_SPARK_POOLS_DESCRIPTION = "(workspace) Manage Apache Spark pools." COMMAND_VARIABLES_DESCRIPTION = "(workspace) Manage variables." -COMMAND_DESCRIBE_DESCRIPTION = "Show commands supported by each Fabric element or path." +COMMAND_DESCRIBE_DESCRIPTION = "Show available commands for a resource." # File system command descriptions COMMAND_FS_MV_DESCRIPTION = "Move an item or file." @@ -172,23 +172,21 @@ COMMAND_FS_PWD_DESCRIPTION = "Print the current working directory." COMMAND_FS_OPEN_DESCRIPTION = "Open a workspace or item in browser." COMMAND_FS_EXPORT_DESCRIPTION = "Export an item." -COMMAND_FS_GET_DESCRIPTION = "Get a workspace or item property." -COMMAND_FS_IMPORT_DESCRIPTION = "Import an item (create/modify)." -COMMAND_FS_SET_DESCRIPTION = "Set a workspace or item property." +COMMAND_FS_GET_DESCRIPTION = "Get workspace or item properties." +COMMAND_FS_IMPORT_DESCRIPTION = "Import an item to create or update it." +COMMAND_FS_SET_DESCRIPTION = "Set workspace or item properties." COMMAND_FS_CLEAR_DESCRIPTION = "Clear the terminal screen." COMMAND_FS_LN_DESCRIPTION = "Create a shortcut." COMMAND_FS_START_DESCRIPTION = "Start a resource." COMMAND_FS_STOP_DESCRIPTION = "Stop a resource." -COMMAND_FS_ASSIGN_DESCRIPTION = "Assign a resource to a workspace." +COMMAND_FS_ASSIGN_DESCRIPTION = "Assign a capacity or resource to a workspace." COMMAND_FS_UNASSIGN_DESCRIPTION = "Unassign a resource from a workspace." COMMAND_FS_LS_DESCRIPTION = "List workspaces, items, and files." -COMMAND_FS_MKDIR_DESCRIPTION = "Create a new workspace, item, or directory." +COMMAND_FS_MKDIR_DESCRIPTION = "Create a workspace, item, or directory." COMMAND_FS_RM_DESCRIPTION = "Delete a workspace, item, or file." # Label command descriptions -COMMAND_LABELS_LIST_LOCAL_DESCRIPTION = ( - "List labels from `local_definition_labels` setting." -) +COMMAND_LABELS_LIST_LOCAL_DESCRIPTION = "List configured sensitivity labels." COMMAND_LABELS_SET_DESCRIPTION = "Set a sensitivity label on an item." COMMAND_LABELS_RM_DESCRIPTION = "Remove a sensitivity label from an item." diff --git a/src/fabric_cli/parsers/fab_acls_parser.py b/src/fabric_cli/parsers/fab_acls_parser.py index db822693..590cd608 100644 --- a/src/fabric_cli/parsers/fab_acls_parser.py +++ b/src/fabric_cli/parsers/fab_acls_parser.py @@ -11,12 +11,12 @@ commands = { "Commands": { - get_os_specific_command("ls"): "List ACLs for a workspace, item, or OneLake.", + get_os_specific_command("ls"): "List ACLs for a workspace, item, or OneLake resource.", get_os_specific_command( "rm" - ): "Remove an ACL from a workspace, gateway or connection.", - "set": "Set access controls on a workspace.", - "get": "Get ACL details for a workspace, item or OneLake.", + ): "Remove an ACL from a workspace, gateway, or connection.", + "set": "Set ACLs on a workspace, gateway, or connection.", + "get": "Get ACL details for a workspace, item, or OneLake resource.", }, } diff --git a/src/fabric_cli/parsers/fab_auth_parser.py b/src/fabric_cli/parsers/fab_auth_parser.py index 56e2442b..9a7e4cd5 100644 --- a/src/fabric_cli/parsers/fab_auth_parser.py +++ b/src/fabric_cli/parsers/fab_auth_parser.py @@ -10,9 +10,9 @@ commands = { "Commands": { - "login": "Log in to a Fabric account.", - "logout": "Log out of a Fabric account.", - "status": "Display active account and authentication state.", + "login": "Authenticate with Fabric.", + "logout": "End the current authentication session.", + "status": "Show authentication status.", }, } diff --git a/src/fabric_cli/parsers/fab_config_parser.py b/src/fabric_cli/parsers/fab_config_parser.py index 6ad0b3b7..54bb919e 100644 --- a/src/fabric_cli/parsers/fab_config_parser.py +++ b/src/fabric_cli/parsers/fab_config_parser.py @@ -13,9 +13,9 @@ commands = { "Commands": { "clear-cache": "Clear the CLI cache.", - "get": "Print the value of a given configuration key.", - get_os_specific_command("ls"): "List all configuration keys and their values.", - "set": "Set a configuration key to a specified value.", + "get": "Get a configuration value.", + get_os_specific_command("ls"): "List all configuration settings.", + "set": "Set a configuration value.", } } diff --git a/src/fabric_cli/parsers/fab_jobs_parser.py b/src/fabric_cli/parsers/fab_jobs_parser.py index 65194516..3e961a6f 100644 --- a/src/fabric_cli/parsers/fab_jobs_parser.py +++ b/src/fabric_cli/parsers/fab_jobs_parser.py @@ -11,14 +11,14 @@ commands = { "Commands": { - "start": "Start an item (async).", - "run": "Run an item (sync).", - "run-cancel": "Cancel an item or scheduled run.", - "run-list": "Retrieve the status of an item or scheduled job run.", + "start": "Start an item asynchronously.", + "run": "Run an item synchronously.", + "run-cancel": "Cancel a running or scheduled job.", + "run-list": "List job runs for an item.", "run-update": "Update a scheduled job.", "run-rm": "Remove a scheduled job.", - "run-sch": "Schedule a job for an item (pipelines, notebooks, and Spark job definitions).", - "run-status": "Get details of an item or scheduled job run.", + "run-sch": "Schedule a job for an item.", + "run-status": "Get job run status.", }, } diff --git a/src/fabric_cli/parsers/fab_labels_parser.py b/src/fabric_cli/parsers/fab_labels_parser.py index b5b4e4f4..5b3e442f 100644 --- a/src/fabric_cli/parsers/fab_labels_parser.py +++ b/src/fabric_cli/parsers/fab_labels_parser.py @@ -11,9 +11,9 @@ commands = { "Commands": { - "list-local": "List labels from 'local_definition_labels' setting.", - "set": "Set a sensitivity label.", - get_os_specific_command("rm"): "Remove a sensitivity label.", + "list-local": "List configured sensitivity labels.", + "set": "Set a sensitivity label on an item.", + get_os_specific_command("rm"): "Remove a sensitivity label from an item.", }, } diff --git a/src/fabric_cli/parsers/fab_tables_parser.py b/src/fabric_cli/parsers/fab_tables_parser.py index e4db5d2c..f40cb00f 100644 --- a/src/fabric_cli/parsers/fab_tables_parser.py +++ b/src/fabric_cli/parsers/fab_tables_parser.py @@ -10,10 +10,10 @@ commands = { "Commands": { - "load": "Load data into a table in the lakehouse.", + "load": "Load data into a lakehouse table.", "optimize": "Optimize a Delta table.", - "schema": "Display the schema of a Delta table.", - "vacuum": "Vacuum a Delta table by removing old files.", + "schema": "Show the schema of a Delta table.", + "vacuum": "Clean up old files in a Delta table.", }, } diff --git a/src/fabric_cli/utils/fab_commands.py b/src/fabric_cli/utils/fab_commands.py index 46ec8b1f..7d391eec 100644 --- a/src/fabric_cli/utils/fab_commands.py +++ b/src/fabric_cli/utils/fab_commands.py @@ -6,23 +6,23 @@ COMMANDS = { "Core Commands": { - "assign": "Assign a resource to a workspace.", - "cd": "Change to the specified directory.", - get_os_specific_command("cp"): "Copy an item or file to a destination.", + "assign": "Assign a capacity or resource to a workspace.", + "cd": "Change to a workspace, item, or folder.", + get_os_specific_command("cp"): "Copy an item or file.", "export": "Export an item.", "exists": "Check if a workspace, item, or file exists.", - "get": "Get a workspace or item property.", - "import": "Import an item to create or modify it.", + "get": "Get workspace or item properties.", + "import": "Import an item to create or update it.", get_os_specific_command("ls"): "List workspaces, items, and files.", get_os_specific_command("ln"): "Create a shortcut.", - "mkdir": "Create a new workspace, item, or directory.", + "mkdir": "Create a workspace, item, or directory.", get_os_specific_command("mv"): "Move an item or file.", "open": "Open a workspace or item in the browser.", "pwd": "Print the current working directory.", get_os_specific_command( "rm" - ): "Delete a workspace, item, or file. Use with caution.", - "set": "Set a workspace or item property.", + ): "Delete a workspace, item, or file.", + "set": "Set workspace or item properties.", "start": "Start a resource.", "stop": "Stop a resource.", "unassign": "Unassign a resource from a workspace.", From 336fa7b056dad269c3f7c9f94a59a983a162c4df Mon Sep 17 00:00:00 2001 From: Jeremy Hoover Date: Wed, 7 Jan 2026 15:54:27 +0200 Subject: [PATCH 2/2] Address PR feedback: restore warnings, technical terms, and add Oxford commas - Restore 'Use with caution' warning for rm command (destructive action) - Add Oxford commas before 'or' in ACL description lists for consistency - Restore 'element or path' context in DESCRIBE_DESCRIPTION for discoverability - Keep 'Log in' for login (distinct from parent 'Authenticate with Fabric') - Restore 'Display active account and authentication state' for status command - Restore 'key' terminology in config commands for technical precision - Restore 'to a destination' in cp command to clarify two-arg semantics - Keep 'Retrieve the status' for run-list (preserves semantics) - Restore item type examples in run-sch for discoverability - Keep 'Vacuum' technical term for Delta Lake searchability --- src/fabric_cli/core/fab_constant.py | 8 ++++---- src/fabric_cli/parsers/fab_auth_parser.py | 4 ++-- src/fabric_cli/parsers/fab_config_parser.py | 6 +++--- src/fabric_cli/parsers/fab_jobs_parser.py | 6 +++--- src/fabric_cli/parsers/fab_tables_parser.py | 2 +- src/fabric_cli/utils/fab_commands.py | 4 ++-- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/fabric_cli/core/fab_constant.py b/src/fabric_cli/core/fab_constant.py index 712ed0fa..66b3ede2 100644 --- a/src/fabric_cli/core/fab_constant.py +++ b/src/fabric_cli/core/fab_constant.py @@ -131,18 +131,18 @@ # Command descriptions COMMAND_AUTH_DESCRIPTION = "Authenticate with Fabric." -COMMAND_AUTH_STATUS_DESCRIPTION = "Show authentication status." +COMMAND_AUTH_STATUS_DESCRIPTION = "Display active account and authentication state." COMMAND_FS_DESCRIPTION = "Workspace, item and file system operations." COMMAND_JOBS_DESCRIPTION = "Manage and schedule jobs." COMMAND_TABLES_DESCRIPTION = "Manage Delta tables." COMMAND_SHORTCUTS_DESCRIPTION = "Manage shorcuts." COMMAND_ACLS_DESCRIPTION = "Manage access control lists [admin]." COMMAND_ACLS_LS_DESCRIPTION = ( - "List ACLs for a workspace, item, gateway, connection or OneLake resource." + "List ACLs for a workspace, item, gateway, connection, or OneLake resource." ) COMMAND_ACLS_RM_DESCRIPTION = "Remove an ACL from a workspace, gateway, or connection." COMMAND_ACLS_GET_DESCRIPTION = ( - "Get ACL details for a workspace, item, gateway, connection or OneLake resource." + "Get ACL details for a workspace, item, gateway, connection, or OneLake resource." ) COMMAND_ACLS_SET_DESCRIPTION = "Set ACLs on a workspace, gateway, or connection." COMMAND_CONFIG_DESCRIPTION = "Manage CLI configuration." @@ -163,7 +163,7 @@ ) COMMAND_SPARK_POOLS_DESCRIPTION = "(workspace) Manage Apache Spark pools." COMMAND_VARIABLES_DESCRIPTION = "(workspace) Manage variables." -COMMAND_DESCRIBE_DESCRIPTION = "Show available commands for a resource." +COMMAND_DESCRIBE_DESCRIPTION = "Show commands supported by each Fabric element or path." # File system command descriptions COMMAND_FS_MV_DESCRIPTION = "Move an item or file." diff --git a/src/fabric_cli/parsers/fab_auth_parser.py b/src/fabric_cli/parsers/fab_auth_parser.py index 9a7e4cd5..da378eae 100644 --- a/src/fabric_cli/parsers/fab_auth_parser.py +++ b/src/fabric_cli/parsers/fab_auth_parser.py @@ -10,9 +10,9 @@ commands = { "Commands": { - "login": "Authenticate with Fabric.", + "login": "Log in to a Fabric account.", "logout": "End the current authentication session.", - "status": "Show authentication status.", + "status": "Display active account and authentication state.", }, } diff --git a/src/fabric_cli/parsers/fab_config_parser.py b/src/fabric_cli/parsers/fab_config_parser.py index 54bb919e..f63957c1 100644 --- a/src/fabric_cli/parsers/fab_config_parser.py +++ b/src/fabric_cli/parsers/fab_config_parser.py @@ -13,9 +13,9 @@ commands = { "Commands": { "clear-cache": "Clear the CLI cache.", - "get": "Get a configuration value.", - get_os_specific_command("ls"): "List all configuration settings.", - "set": "Set a configuration value.", + "get": "Get the value of a configuration key.", + get_os_specific_command("ls"): "List all configuration keys and their values.", + "set": "Set a configuration key to a specified value.", } } diff --git a/src/fabric_cli/parsers/fab_jobs_parser.py b/src/fabric_cli/parsers/fab_jobs_parser.py index 3e961a6f..3bb79355 100644 --- a/src/fabric_cli/parsers/fab_jobs_parser.py +++ b/src/fabric_cli/parsers/fab_jobs_parser.py @@ -14,11 +14,11 @@ "start": "Start an item asynchronously.", "run": "Run an item synchronously.", "run-cancel": "Cancel a running or scheduled job.", - "run-list": "List job runs for an item.", + "run-list": "Retrieve the status of an item or scheduled job run.", "run-update": "Update a scheduled job.", "run-rm": "Remove a scheduled job.", - "run-sch": "Schedule a job for an item.", - "run-status": "Get job run status.", + "run-sch": "Schedule a job for an item (pipelines, notebooks, and Spark job definitions).", + "run-status": "Get details of an item or scheduled job run.", }, } diff --git a/src/fabric_cli/parsers/fab_tables_parser.py b/src/fabric_cli/parsers/fab_tables_parser.py index f40cb00f..31a93abd 100644 --- a/src/fabric_cli/parsers/fab_tables_parser.py +++ b/src/fabric_cli/parsers/fab_tables_parser.py @@ -13,7 +13,7 @@ "load": "Load data into a lakehouse table.", "optimize": "Optimize a Delta table.", "schema": "Show the schema of a Delta table.", - "vacuum": "Clean up old files in a Delta table.", + "vacuum": "Vacuum a Delta table by removing old files.", }, } diff --git a/src/fabric_cli/utils/fab_commands.py b/src/fabric_cli/utils/fab_commands.py index 7d391eec..f40cba3c 100644 --- a/src/fabric_cli/utils/fab_commands.py +++ b/src/fabric_cli/utils/fab_commands.py @@ -8,7 +8,7 @@ "Core Commands": { "assign": "Assign a capacity or resource to a workspace.", "cd": "Change to a workspace, item, or folder.", - get_os_specific_command("cp"): "Copy an item or file.", + get_os_specific_command("cp"): "Copy an item or file to a destination.", "export": "Export an item.", "exists": "Check if a workspace, item, or file exists.", "get": "Get workspace or item properties.", @@ -21,7 +21,7 @@ "pwd": "Print the current working directory.", get_os_specific_command( "rm" - ): "Delete a workspace, item, or file.", + ): "Delete a workspace, item, or file. Use with caution.", "set": "Set workspace or item properties.", "start": "Start a resource.", "stop": "Stop a resource.",