Reorganize documentation for better clarity and user experience

[joshrotenberg]

Documentation Reorganization Plan

Problem Statement

The current documentation feels overwhelming and could benefit from a clearer hierarchy and better organization. The README is too detailed for a quick overview, and the docs could be better structured for different user personas.

Goals

1. Make README a concise entry point that gets users started quickly
2. Organize documentation by user journey and common tasks
3. Separate reference documentation from tutorials/guides
4. Improve command documentation organization

Proposed Structure

README.md (Simplified)

# redisctl
[Badges]

Brief one-paragraph description

## Features
- 5-6 bullet points highlighting key features

## Installation
### From Binary Releases
### From Cargo
### Using Docker

## Quick Start
### 1. Configure Authentication
- Simple example for Cloud
- Simple example for Enterprise

### 2. Basic Usage Examples
- List databases
- Create a database
- Check operation status

## Documentation
Link to full documentation site

## Contributing
Brief contributing guidelines

## License

Documentation Site Structure

# Introduction
- What is redisctl
- Key concepts (profiles, deployments, async operations)
- Architecture overview

# Quick Start
- Installation (detailed)
- First-time setup
- Your first commands
- Common workflows

# Configuration
- Profiles and authentication
- Environment variables
- Configuration file reference

# Core Concepts
- Async operations and --wait flags
- Output formats and filtering
- Smart command routing
- Error handling

# Redis Cloud Commands
## Subscriptions
- list
- get
- create
- update
- delete
## Databases
- list
- get  
- create
- update
- delete
- backup/import/export
## Network
- VPC Peering
- Private Service Connect
- Transit Gateway
## Access Control
- ACL rules
- ACL roles
- Users
## Account Management
- Cloud accounts
- Payment methods
- Settings

# Redis Enterprise Commands
## Cluster
- info
- update
- policy
- certificates
## Databases (BDB)
- list
- get
- create
- update
- delete
- backup/import/export
## Nodes
- list
- get
- update
- actions
## RBAC
- Users
- Roles
- LDAP
## Statistics
- Cluster stats
- Database stats
- Node stats
- Shard stats
## Modules
- list
- upload
- configure
- delete
## Logs
- list
- filter
- export

# API Reference
## Raw API Access
- Using `api cloud`
- Using `api enterprise`
- Request/response formats
## Smart Commands
- How routing works
- Available smart commands
- Deployment detection

# Tutorials
- Managing a production database
- Setting up monitoring
- Automating deployments
- Migrating between environments

# Reference
## CLI Reference
- Complete command list
- Global options
- Exit codes
## Environment Variables
- Complete list
- Precedence rules
## Configuration File
- Schema
- Examples
## Troubleshooting
- Common issues
- Debug logging
- Getting help

# Developer Guide
- Using as a library
- Adding new commands
- Testing
- Contributing

Implementation Plan

Phase 1: README Simplification

1. Move detailed content to docs
2. Keep only essential getting-started info
3. Add clear links to documentation

Phase 2: Command Documentation

1. Create one page per command group
2. Include:
   • Command syntax
   • All flags/options
   • Real-world examples
   • Common patterns
   • Related commands

Phase 3: Tutorials and Guides

1. Create task-oriented guides
2. Focus on common workflows
3. Include troubleshooting tips

Phase 4: Reference Documentation

1. Auto-generate from CLI help where possible
2. Maintain comprehensive option reference
3. Keep updated with new features

Benefits

1. For new users: Clear path from installation to first success
2. For regular users: Easy-to-find command reference
3. For power users: Complete API documentation
4. For developers: Clear contribution guidelines

Considerations

• Keep docs in sync with code (consider auto-generation)
• Ensure all examples are tested and working
• Add search functionality to docs site
• Consider versioned documentation for major releases

Next Steps

1. Get feedback on proposed structure
2. Create tracking issues for each phase
3. Start with README simplification
4. Gradually migrate content to new structure

[joshrotenberg]

Documentation reorganization complete!

All phases have been successfully implemented:

• ✅ Phase 1: Simplified README (PR docs: simplify README to focus on getting started #249)
• ✅ Phase 2: Command Documentation (PR docs: add comprehensive command documentation structure (Phase 2) #250)
• ✅ Phase 3: Tutorials (PR docs: add comprehensive tutorials for real-world usage (Phase 3) #254)
• ✅ Phase 4: Reference Documentation (PR docs: add comprehensive reference documentation (Phase 4) #255)
• ✅ Phase 0: Cleanup (PR docs: Phase 0 - Clean up non-book documentation and fix API endpoints #257)

The documentation is now well-organized with:

• Concise README focused on getting started
• Comprehensive mdBook with tutorials, command docs, and reference material
• Clean structure without duplicate or outdated files
• Fixed API endpoint documentation

Thanks for the great plan! The docs are much more approachable now.