Documentation and UX cleanup tasks

[joshrotenberg]

Summary

Collection of smaller documentation and UX improvements identified during the documentation reorganization.

Tasks

Profile Configuration Clarity

• Add note to README about where profiles are stored
  • Linux: ~/.config/redisctl/config.toml
  • macOS: ~/.config/redisctl/config.toml (preferred) or ~/Library/Application Support/com.redis.redisctl/config.toml
  • Windows: %APPDATA%\redis\redisctl\config.toml
• Update profile subcommand to show config file location
  • Add profile path command to show config file location
  • Show path in profile list output header
  • Add note in profile set success message about where it was saved
• Add example of what the config file looks like in README quick start

Command Output Improvements

• Make error messages more actionable (suggest next steps)
• Add hints when commands fail (e.g., "Did you mean...")
• Improve --help output with more examples

Documentation Additions

• Add section about debugging with RUST_LOG
• Document how to use with Docker in more detail
• Add troubleshooting section to README for common first-time issues
• Create a "Common Recipes" section with copy-paste examples

Shell Completion Improvements

• Test and document shell completions for all supported shells
• Add note about reloading shell after installing completions
• Consider auto-detecting shell and suggesting completion command

Configuration File Features

• Document environment variable expansion in config files
• Add example showing ${VAR:-default} syntax
• Consider adding config validate command

Quick Start Improvements

• Add "verify your setup" section after configuration
• Include test command to verify credentials work
• Add common first commands to try

Related Issues

• Part of Reorganize documentation for better clarity and user experience #243 (Documentation Reorganization)
• Improves user onboarding experience
• Makes configuration more discoverable

Priority

Medium - These are quality-of-life improvements that will help new users get started more easily.

[joshrotenberg]

Progress update - the following tasks have been completed:

✅ Completed Tasks

Profile Configuration Clarity:

• ✅ Added note to README about where profiles are stored (PR docs: add profile storage location to README #252)
• ✅ Added profile path command to show config file location (PR feat: add profile path command and improve config visibility #253)
• ✅ Show path in profile list output header (PR feat: add profile path command and improve config visibility #253)
• ✅ Add note in profile set success message about where it was saved (PR feat: add profile path command and improve config visibility #253)

Documentation Additions:

• ✅ Added section about debugging with RUST_LOG (in reference/environment-variables.md and troubleshooting.md)
• ✅ Added troubleshooting section (comprehensive troubleshooting guide in reference docs)

Configuration File Features:

• ✅ Documented environment variable expansion in config files (in reference/config-file.md)
• ✅ Added example showing ${VAR:-default} syntax

Quick Start Improvements:

• ✅ Added "verify your setup" section after configuration (in quickstart.md)
• ✅ Included test command to verify credentials work

Still TODO:

• Command output improvements (error messages, hints, help output)
• Shell completion improvements
• Docker documentation details
• Common Recipes section
• Config validate command

[joshrotenberg]

Documentation tasks complete! PR #258 adds the remaining documentation improvements:

✅ Just Completed

• Added example config file to README quick start
• Enhanced Quick Start with verification steps and common first commands
• Added Docker usage section to README
• Created comprehensive shell completions guide for all shells
• Added Common Recipes placeholder (previewing upcoming workflow system)

📋 Summary of All Completed Documentation Tasks

Profile Configuration Clarity: ✅ All complete (PRs #252, #253)
Documentation Additions: ✅ All complete (various PRs)
Configuration File Features: ✅ All complete
Quick Start Improvements: ✅ All complete

🔨 Remaining (Code Changes, Not Documentation)

• Command output improvements (error messages, hints)
• Config validate command
• Auto-detect shell for completions

The documentation reorganization is now fully complete! Ready to shift focus to workflows and other features.