docs: reorganize user docs into guides and reference

Sunil Thaha · Sunil Thaha · commit 6710d0905844 · 2025-10-14T14:26:46.000+10:00
Reorganize user documentation to better distinguish between step-by-step
tutorials (guides) and detailed feature specifications (reference). This
improves documentation discoverability and helps users quickly find the
right type of documentation for their needs.

Motivation:

Users need different types of documentation for different purposes:
- Guides answer "How do I accomplish task X?" with step-by-step instructions
- Reference answers "What are all the options for feature Y?" with comprehensive specifications

The previous structure mixed both types in the guides/ directory, making it
harder for users to find what they need. Tutorial-style content (validating
Prometheus, setting up Grafana) was alongside comprehensive specifications
(PowerMonitor CR, ConfigMaps API).

Changes:

- Move guides/power-monitor.md → reference/power-monitor.md
  (comprehensive PowerMonitor CR specification and configuration options)
- Move guides/custom-configmaps.md → reference/custom-configmaps.md
  (detailed additionalConfigMaps feature documentation with examples)
- Update README.md with two distinct sections:
  - "Guides" section: step-by-step tutorials for common tasks
  - "Reference Documentation" section: detailed feature specs
- Update all cross-references in 9 files:
  - installation/openshift.md
  - installation/kubernetes.md
  - installation/monitoring-stack-kubernetes.md
  - guides/upgrading.md
  - guides/grafana-dashboard.md
  - guides/troubleshooting.md
  - guides/validating-prometheus-integration.md
  - guides/experimental/redfish.md
  - reference/power-monitor.md (internal references)
  - reference/custom-configmaps.md (internal references)

Result:

guides/                  # Step-by-step tutorials
  ├── experimental/
  │   └── redfish.md
  ├── grafana-dashboard.md
  ├── troubleshooting.md
  ├── upgrading.md
  └── validating-prometheus-integration.md

reference/              # Feature documentation &amp; specs
  ├── api.md
  ├── custom-configmaps.md
  ├── power-monitor.md
  └── uninstallation.md

Signed-off-by: Sunil Thaha &lt;sthaha@redhat.com&gt;
diff --git a/docs/user/README.md b/docs/user/README.md
@@ -29,30 +29,29 @@ Choose your platform to begin:
   - Required only if you want metrics visualization
   - Not needed for basic Kepler installation
 
-## Usage Guides
+## Guides
 
-Once installed, learn how to use Kepler Operator:
+Step-by-step tutorials for common tasks:
 
-- **[Creating PowerMonitor Resources](guides/power-monitor.md)** - Deploy and configure Kepler on your cluster
-- **[Custom ConfigMaps](guides/custom-configmaps.md)** - Advanced Kepler configuration with custom ConfigMaps
 - **[Validating Prometheus Integration](guides/validating-prometheus-integration.md)** - Verify Prometheus is scraping Kepler metrics
 - **[Setting up Grafana Dashboards](guides/grafana-dashboard.md)** - Visualize energy metrics
 - **[Upgrading](guides/upgrading.md)** - Upgrade the operator (Helm and OLM)
+- **[Troubleshooting Guide](guides/troubleshooting.md)** - Common issues and platform-specific solutions
 
 ### Experimental Features
 
 ⚠️ These features are experimental and may change in future versions:
 
 - **[Redfish BMC Power Monitoring](guides/experimental/redfish.md)** - Platform-level power consumption via Baseboard Management Controllers
 
-## Troubleshooting and Support
-
-- **[Troubleshooting Guide](guides/troubleshooting.md)** - Common issues and platform-specific solutions
-- **[Uninstallation](reference/uninstallation.md)** - Clean removal procedures
-
 ## Reference Documentation
 
-- **[API Reference](reference/api.md)** - Complete PowerMonitor API specification
+Detailed feature documentation and specifications:
+
+- **[PowerMonitor Resources](reference/power-monitor.md)** - Complete PowerMonitor CR specification and configuration options
+- **[Custom ConfigMaps](reference/custom-configmaps.md)** - Advanced Kepler configuration using additionalConfigMaps
+- **[API Reference](reference/api.md)** - Complete API specification
+- **[Uninstallation](reference/uninstallation.md)** - Clean removal procedures
 
 ## Developer Documentation
 
diff --git a/docs/user/guides/experimental/redfish.md b/docs/user/guides/experimental/redfish.md
@@ -549,8 +549,8 @@ Planned improvements for future versions:
 
 ## Related Documentation
 
-- **[PowerMonitor Guide](../power-monitor.md)** - Complete PowerMonitor configuration
-- **[Custom ConfigMaps Guide](../custom-configmaps.md)** - Using additionalConfigMaps
+- **[PowerMonitor Guide](../../reference/power-monitor.md)** - Complete PowerMonitor configuration
+- **[Custom ConfigMaps Guide](../../reference/custom-configmaps.md)** - Using additionalConfigMaps
 - **[Kepler Redfish Proposal](https://github.com/sustainable-computing-io/kepler/blob/main/doc/dev/EP_001-redfish-support.md)** - Technical design document
 
 ## Getting Help
diff --git a/docs/user/guides/grafana-dashboard.md b/docs/user/guides/grafana-dashboard.md
@@ -353,6 +353,6 @@ For more troubleshooting, see the [Troubleshooting Guide](./troubleshooting.md#k
 
 ## Next Steps
 
-- **[PowerMonitor Configuration](./power-monitor.md)** - Configure PowerMonitor resources
+- **[PowerMonitor Configuration](../reference/power-monitor.md)** - Configure PowerMonitor resources
 - **[Troubleshooting](./troubleshooting.md)** - Diagnose common issues
 - **[Validating Prometheus Integration](./validating-prometheus-integration.md)** - Deep dive into Prometheus setup
diff --git a/docs/user/guides/troubleshooting.md b/docs/user/guides/troubleshooting.md
@@ -835,6 +835,6 @@ If issues persist after troubleshooting:
 
 ## Additional Resources
 
-- **[PowerMonitor Guide](./power-monitor.md)** - Creating and configuring PowerMonitors
-- **[PowerMonitor Configuration](./power-monitor.md)** - Configuration options
+- **[PowerMonitor Guide](../reference/power-monitor.md)** - Creating and configuring PowerMonitors
+- **[PowerMonitor Configuration](../reference/power-monitor.md)** - Configuration options
 - **[API Reference](../reference/api.md)** - Complete API specification
diff --git a/docs/user/guides/upgrading.md b/docs/user/guides/upgrading.md
@@ -447,4 +447,4 @@ For more troubleshooting, see the [Troubleshooting Guide](./troubleshooting.md).
 ## Next Steps
 
 - **[Troubleshooting Guide](./troubleshooting.md)** - Diagnose upgrade issues
-- **[PowerMonitor Configuration](./power-monitor.md)** - Review configuration options for new versions
+- **[PowerMonitor Configuration](../reference/power-monitor.md)** - Review configuration options for new versions
diff --git a/docs/user/guides/validating-prometheus-integration.md b/docs/user/guides/validating-prometheus-integration.md
@@ -501,7 +501,7 @@ helm upgrade prometheus prometheus-community/kube-prometheus-stack \
 Once you've validated that Prometheus is scraping Kepler metrics:
 
 - **[Set up Grafana Dashboards](./grafana-dashboard.md)** to visualize the metrics
-- **[Custom ConfigMaps](./custom-configmaps.md)** to adjust metric levels and collection settings
+- **[Custom ConfigMaps](../reference/custom-configmaps.md)** to adjust metric levels and collection settings
 - **[Set up Alerts](https://prometheus.io/docs/alerting/latest/overview/)** for abnormal power consumption
 
 ---
diff --git a/docs/user/installation/kubernetes.md b/docs/user/installation/kubernetes.md
@@ -224,8 +224,8 @@ For complete setup and troubleshooting instructions, see:
 
 Now that the operator is installed, you can:
 
-1. **[Create a PowerMonitor resource](../guides/power-monitor.md)** to deploy Kepler
-2. **[Custom ConfigMaps](../guides/custom-configmaps.md)** for advanced Kepler configuration
+1. **[Create a PowerMonitor resource](../reference/power-monitor.md)** to deploy Kepler
+2. **[Custom ConfigMaps](../reference/custom-configmaps.md)** for advanced Kepler configuration
 3. **[Set up Monitoring Stack](./monitoring-stack-kubernetes.md)** (optional) - If you want to visualize metrics
 4. **[Validate Prometheus Integration](../guides/validating-prometheus-integration.md)** (if using Prometheus) - Ensure metrics are being scraped
 5. **[Set up Grafana dashboards](../guides/grafana-dashboard.md)** (if using Grafana) - Visualize metrics
diff --git a/docs/user/installation/monitoring-stack-kubernetes.md b/docs/user/installation/monitoring-stack-kubernetes.md
@@ -215,7 +215,7 @@ kubectl get servicemonitor -A | grep power-monitor
 Now that your monitoring stack is ready:
 
 1. **[Install Kepler Operator](./kubernetes.md)** with ServiceMonitor enabled
-2. **[Create a PowerMonitor](../guides/power-monitor.md)** to deploy Kepler
+2. **[Create a PowerMonitor](../reference/power-monitor.md)** to deploy Kepler
 3. **[Import Grafana dashboards](../guides/grafana-dashboard.md)** to visualize metrics
 
 ## Troubleshooting
diff --git a/docs/user/installation/openshift.md b/docs/user/installation/openshift.md
@@ -164,8 +164,8 @@ EOF
 
 Now that the operator is installed:
 
-1. **[Create a PowerMonitor resource](../guides/power-monitor.md)** to deploy Kepler
-2. **[Configure PowerMonitor](../guides/power-monitor.md)** for your cluster
+1. **[Create a PowerMonitor resource](../reference/power-monitor.md)** to deploy Kepler
+2. **[Configure PowerMonitor](../reference/power-monitor.md)** for your cluster
 3. **[Set up Grafana dashboards](../guides/grafana-dashboard.md)** to visualize energy metrics
 
 ## Troubleshooting
diff --git a/docs/user/reference/custom-configmaps.md b/docs/user/reference/custom-configmaps.md
diff --git a/docs/user/reference/power-monitor.md b/docs/user/reference/power-monitor.md
