docs: Improve help text clarity and consistency across all commands

[jeremydhoover-blip]

Summary

This PR implements comprehensive UX writing improvements to all user-facing help text in the Fabric CLI, making command descriptions more concise, consistent, and user-focused.

Changes Made

Core Commands (fab_commands.py)

• Updated 8 command descriptions for clarity
• Removed redundant words ("new", "specified", "to a destination")
• Made language more specific and action-oriented

Command Constants (fab_constant.py)

• Updated 15+ description constants
• Standardized terminology across all commands
• Improved specificity (e.g., "Manage tables" → "Manage Delta tables")

Parser Updates (6 files)

• Auth: "Log in" → "Authenticate with Fabric"
• Config: Simplified verbose descriptions
• ACL: Standardized terminology and parallel structure
• Jobs: Clarified with "asynchronously"/"synchronously"
• Labels: Removed internal config references
• Tables: "Display" → "Show", "Vacuum" → "Clean up"

UX Writing Principles Applied

• ✅ Concise language - removed redundant words
• ✅ Consistent terminology - standardized across commands
• ✅ Active voice - direct action verbs
• ✅ Technical accuracy - kept developer-familiar terms
• ✅ Parallel structure - similar patterns across commands

Testing

• Changie entry added
• Tested with fab --help
• Tested command group help (fab auth --help, etc.)
• Verified no breaking changes

References

• Based on comprehensive UX writing analysis
• Follows Microsoft Style Guide principles
• Implements Fabric UX System content guidelines

[jeremydhoover-blip]

@microsoft-github-policy-service agree company="Microsoft"

[HasanAboShally]

PR Review: Help Text Improvements

Thanks for this contribution to improve CLI help text consistency! UX writing for command-line interfaces is often overlooked, and this PR addresses that well.

📚 Review Context

I reviewed this PR against established CLI design guidelines and industry patterns:

Reference Materials:

• Command Line Interface Guidelines (clig.dev) — The definitive modern CLI design guide
• Google Developer Style Guide — Command-line documentation standards
• Microsoft Writing Style Guide — Procedural writing best practices

Industry CLI Patterns Examined:

• Docker CLI — Concise, action-oriented descriptions (e.g., "Manage containers", "Build an image from a Dockerfile")
• kubectl — Consistent verb usage, technical precision (e.g., "Delete resources", "Display detailed state")
• Azure CLI — Microsoft's own patterns for CLI help text
• Git — The gold standard for CLI discoverability

✅ What This PR Does Well

1. Consistent verb usage — Standardizing on "Show" instead of mixing "Display/Print/Show"
2. Removing redundant words — "Create a new" → "Create a" follows clig.dev's "saying just enough" principle
3. Better specificity — "Manage tables" → "Manage Delta tables" helps discoverability
4. Action-oriented language — Using imperative verbs throughout

🔴 Required Changes

File	Line	Issue
fab_commands.py	24	Restore "Use with caution." for rm — CLI guidelines recommend warnings for destructive commands
Multiple files	Various	Standardize Oxford commas — Currently inconsistent before "or" in lists

🟡 Recommended Changes

File	Line	Issue
fab_constant.py	166	COMMAND_DESCRIBE_DESCRIPTION loses "path" context important for discoverability
fab_auth_parser.py	13	login now duplicates parent auth description — subcommands should be distinct
fab_constant.py	134	COMMAND_AUTH_STATUS_DESCRIPTION loses "active account" detail
fab_jobs_parser.py	17	run-list changed semantics (status → list) — verify correctness

💡 Suggestions (Non-blocking)

File	Line	Issue
fab_constant.py	139	COMMAND_ACLS_DESCRIPTION is longer than original
fab_config_parser.py	16-18	Lost "key" terminology which is technically precise
fab_jobs_parser.py	20	run-sch lost item type examples (pipelines, notebooks)
fab_tables_parser.py	16	vacuum loses searchable technical term
fab_commands.py	11	cp lost "to a destination" which clarifies two-arg semantics

📖 Key CLI Help Text Principles (for future reference)

From clig.dev and industry standards:

1. Concise but complete — "Say just enough" but don't lose critical context
2. Discoverable — Help text should help users understand what's possible
3. Consistent — Same patterns across all commands (verbs, structure, punctuation)
4. Warn on danger — Destructive commands should indicate risk
5. Technically precise — Use correct terminology users will search for
6. Hierarchically distinct — Parent group descriptions ≠ subcommand descriptions

---

Once the required changes are addressed, this is a solid improvement to the CLI's user experience! 🎉

[jeremydhoover-blip]

Thanks for the thorough review and the excellent CLI design resources! I've addressed all the feedback:

✅ Required Changes

1. Restored "Use with caution." for rm command - agreed that destructive commands need warnings
2. Added Oxford commas in ACL descriptions (e.g., "workspace, item, gateway, connection, or OneLake")

✅ Recommended Changes

1. Restored "element or path" in DESCRIBE_DESCRIPTION for better discoverability
2. Changed login back to "Log in to a Fabric account." to differentiate from parent auth description
3. Restored "active account" detail in status command
4. Kept "status" semantics in run-list (changed back to "Retrieve the status...")

✅ Suggestions Implemented

1. Restored "to a destination" for cp to clarify two-arg semantics
2. Kept "key" terminology in config commands for technical precision
3. Restored item type examples in run-sch for discoverability
4. Kept "Vacuum" technical term for Delta Lake searchability

Really appreciate the guidance on CLI UX patterns - especially the point about hierarchically distinct descriptions and keeping searchable technical terms. The clig.dev resource is great and adding it to my flow for future tasks.