Expand User Guide with Setup Walkthrough and Usage Examples

[switch180]

Problem

The current README has only basic setup instructions but lacks comprehensive user documentation. New users need detailed guidance, examples, and troubleshooting help to effectively use the integration.

Current State

The README includes:

• ✅ Basic installation instructions (HACS/manual)
• ✅ Simple configuration steps
• ✅ Feature list
• ❌ No setup walkthrough with screenshots
• ❌ No usage examples
• ❌ No automation examples
• ❌ No troubleshooting guide
• ❌ No FAQ

Missing Documentation

1. Complete Setup Walkthrough

• Pre-requisites checklist (network access, API version, etc.)
• Step-by-step setup with screenshots
  • Finding the integration in HA
  • Entering connection details
  • What to expect during first setup
  • Troubleshooting connection failures
• Post-setup verification
  • Confirming devices discovered
  • Understanding entity naming
  • Initial entity organization

2. Common Use Cases with Examples

Basic Video Routing:

# Example: Route Laptop to Conference Room Display
# Use the video source select entity

Display Mode Configuration:

# Example: Set display to Fast Switch mode at 4K
# Step-by-step guide on when to use each mode

Understanding Display Modes:

• When to use Genlock (zero latency, direct passthrough)
• When to use Genlock Scaling (low latency with resolution conversion)
• When to use Fast Switch modes (multi-source environments)
• Resolution preset selection guide

3. Automation Examples

Meeting Room Scenarios:

# Auto-route laptop when meeting starts
# Disconnect when meeting ends
# Set appropriate display modes

Signage/Display Management:

# Schedule content changes
# Multi-display synchronization
# Fallback source configuration

Monitoring & Alerts:

# Alert on device offline
# Temperature monitoring
# Stream health checks

4. Troubleshooting Guide

Common Issues:

• "Integration won't connect" - Network troubleshooting steps
• "Entities not updating" - Coordinator debugging
• "Video routing fails" - Device compatibility checks
• "Display mode changes don't work" - Mode requirements guide
• "Audio issues" - Audio routing explanation

Debug Logging:

# How to enable debug logging
logger:
  logs:
    custom_components.riverlink: debug

Interpreting Logs:

• What to look for in logs
• Common error messages explained
• When to report bugs

5. FAQ Section

General Questions:

• Q: What SDVoE devices are supported?
• Q: Can I use this with non-BlueRiver devices?
• Q: What's the difference between HDMI and HDMI_AUDIO?
• Q: How do I update the integration?
• Q: Can I rename devices?

Technical Questions:

• Q: Why is polling every 5 seconds?
• Q: What's the difference between display modes?
• Q: How does resolution preset work?
• Q: Can I control audio separately from video?
• Q: What are stream indexes for?

Troubleshooting Questions:

• Q: Why are my entities unavailable?
• Q: Why doesn't my device appear?
• Q: How do I change the API server IP?
• Q: What do I do if routing fails?

Proposed Documentation Structure

README.md (updated)
├── Installation (existing)
├── Configuration (existing)
├── **NEW: Getting Started**
│   ├── Prerequisites
│   ├── Setup Walkthrough (with screenshots)
│   └── Verification Steps
├── **NEW: User Guide**
│   ├── Understanding Entities
│   ├── Basic Video Routing
│   ├── Display Modes Explained
│   ├── Resolution Management
│   └── Audio Routing
├── **NEW: Automation Examples**
│   ├── Meeting Room Automation
│   ├── Display Management
│   └── Monitoring & Alerts
├── **NEW: Troubleshooting**
│   ├── Common Issues
│   ├── Debug Logging
│   └── Getting Help
├── **NEW: FAQ**
└── Support (existing)

OR

docs/user_guide.md (separate file)
└── Comprehensive guide with all sections above

Documentation Standards

• Clear, concise language for non-technical users
• Step-by-step instructions with numbered lists
• Screenshots for UI-heavy steps
• Code examples properly formatted with syntax highlighting
• Cross-references to related documentation
• Version-specific notes where applicable

Success Criteria

• Setup walkthrough complete with screenshots
• At least 5 common use cases documented with examples
• At least 5 automation examples provided
• Troubleshooting guide covers 10+ common issues
• FAQ answers 20+ common questions
• All documentation reviewed for clarity and accuracy

Benefits

• Reduced Support Burden: Users can self-serve common questions
• Faster Onboarding: New users get up and running quickly
• Better Adoption: Clear documentation encourages usage
• Professional Image: Comprehensive docs signal quality
• Community Growth: Good docs attract contributors

Priority

🔴 High

Effort & Complexity

• Effort: Medium
• Complexity: Low (mostly writing, some screenshots)

References

• Current README.md
• See OPEN_ISSUES.md section "Documentation Gaps" for detailed requirements
• Home Assistant Documentation Style Guide