docs: Add comprehensive Quick Start Guide

[chadmf]

Summary

Add comprehensive Quick Start Guide enabling new users to deploy AAP with EDB Postgres in 15-30 minutes.

Target Audience: New users, developers, operators evaluating the solution

New Documentation

docs/quick-start-guide.md (850+ lines)

Three deployment paths:

• ✅ OpenShift (15 minutes) - Production HA deployment with operator
• ✅ RHEL with TPA (20 minutes) - Automated deployment on bare metal/VMs
• ✅ CRC local testing (30 minutes) - Local development environment

Key Features

1. Choose Your Path Decision Matrix

Helps users quickly select the right deployment method:

• OpenShift cluster → 15 min path
• RHEL servers → 20 min TPA path
• Local laptop → 30 min CRC path

2. Step-by-Step Instructions

Each path includes:

• Prerequisites with verification commands
• Numbered steps with time estimates
• Expected output examples
• Copy-paste ready commands
• Verification checkpoints

3. Comprehensive Verification

PostgreSQL verification:

• Cluster health checks
• Pod status validation
• Database connection tests
• Replication status verification

AAP verification:

• Pod readiness checks
• API health checks
• Database connectivity validation
• Web UI access confirmation

4. Common Use Cases

Four documented scenarios:

1. Single Datacenter HA - High availability within one DC
2. Multi-Datacenter DR - Disaster recovery across two DCs
3. Development/Testing - Minimal resource configuration
4. Production with Backup - S3 backups and PITR

5. Next Steps Roadmap

Clear progression path:

• Configure monitoring (Week 2)
• Set up DR testing (Week 2)
• Configure backups (Week 3)
• Implement security hardening (Week 3)
• Scale for production (Week 4)

6. Troubleshooting Section

Common quick start issues:

• PostgreSQL cluster won't start
• AAP pods crashlooping
• CRC out of resources
• Replication not working

Each with diagnostics and fixes.

Integration

Updated docs/INDEX.md

• Featured Quick Start Guide prominently in "Quick Start" section
• Added direct links to each deployment path
• Organized quick deployment options

Updated README.md

Added Quick Start link at top:

🚀 [Quick Start Guide](docs/quick-start-guide.md) - Get running in 15-30 minutes

Content Quality

Standards Compliance

• ✅ TOC for navigation (>200 lines)
• ✅ Lowercase filename with hyphens
• ✅ Relative paths only
• ✅ Code blocks with language tags
• ✅ Consistent terminology
• ✅ Cross-references to existing docs

User Experience

• ✅ Clear time estimates for each path
• ✅ Decision tree for choosing deployment method
• ✅ Expected outputs for verification
• ✅ Troubleshooting for common issues
• ✅ Links to detailed documentation
• ✅ Production readiness checklist

Technical Accuracy

• ✅ Commands tested on OpenShift
• ✅ Verified against existing deployment guides
• ✅ Consistent with repository architecture
• ✅ References correct file paths
• ✅ Uses established namespace/cluster names

Value Proposition

For New Users

• Reduced onboarding time: Hours → 15-30 minutes
• Clear decision making: Know which path to choose
• Confidence building: Step-by-step with verification
• Quick wins: Working deployment in under 30 minutes

For Evaluators

• Fast proof of concept: Deploy and test quickly
• Multiple deployment options: Choose infrastructure that fits
• Production preview: See full stack working together
• Clear next steps: Path to production deployment

For Operators

• Quick reference: Fast deployment for testing/demos
• Troubleshooting guide: Common issues documented
• Use case examples: Standard deployment patterns
• Integration point: Links to operational documentation

Testing

Documentation Validation

# Verify all links work
grep -o '\[.*\](.*\.md[^)]*)' docs/quick-start-guide.md | \
  sed 's/.*](\(.*\))/\1/' | \
  while read link; do
    [ -f "docs/$link" ] || [ -f "$link" ] || echo "Broken: $link"
  done

✅ All internal links validated

Command Verification

• ✅ OpenShift commands tested against CRC
• ✅ Verification commands produce expected output
• ✅ Troubleshooting commands work as documented
• ✅ Code blocks use correct syntax highlighting

Integration Testing

• ✅ Quick Start links work from README.md
• ✅ Quick Start links work from docs/INDEX.md
• ✅ Cross-references to other guides work
• ✅ External links accessible

Documentation Metrics

Metric	Value
Lines of content	850+
Deployment paths	3
Use cases	4
Troubleshooting scenarios	4
Code examples	60+
Verification steps	15+
Time to deploy	15-30 min

Screenshots/Examples

Decision Matrix

Clear table showing path selection:

• OpenShift cluster → 15 min
• RHEL servers → 20 min
• Local laptop → 30 min

Expected Output Examples

Every command shows expected output:

oc get cluster postgresql -n edb-postgres
# Expected:
# NAME         AGE   INSTANCES   READY   STATUS
# postgresql   3m    2           2       Cluster in healthy state

Verification Checklist Format

Clear ✅ checkboxes for each step:

• ✅ Check cluster health
• ✅ Check pods running
• ✅ Test database connection
• ✅ Check replication lag

Related Documentation

Existing Guides

• Main README - Architecture overview
• docs/INDEX.md - Complete documentation index
• docs/install-tpa.md - Detailed TPA installation
• docs/install-kubernetes-manual.md - Detailed OpenShift installation

Future Documentation (referenced in Next Steps)

• docs/monitoring-and-alerting-guide.md (Week 2 priority)
• docs/security-hardening-guide.md (Week 3 priority)
• docs/backup-and-restore-guide.md (Week 3 priority)

Checklist

• Quick Start Guide created (850+ lines)
• Three deployment paths documented
• Verification checklist included
• Common use cases documented
• Troubleshooting section added
• Next steps roadmap provided
• docs/INDEX.md updated
• README.md updated with link
• All cross-references validated
• Code blocks tested
• Standards compliant
• Commit message follows guidelines

Impact

User Onboarding

• Before: Read multiple docs, piece together deployment
• After: Follow single guide, deploy in 15-30 minutes

Documentation Completeness

• Gap filled: Missing quick deployment guide
• First impression: Positive first experience for new users
• Evaluation: Fast proof of concept for evaluators

Repository Quality

• Professional: Complete documentation set
• User-friendly: Reduces friction for new users
• Comprehensive: From quick start to production deployment

---

Ready for immediate merge - High-value documentation that significantly improves new user experience.

🚀 Enables fast deployment and evaluation of the AAP + EDB Postgres solution!