Improve documentation content and organization (#1883)

pavangudiwada · web-flow · commit f4a96e19ba8c · 2025-07-29T19:42:56.000+05:30
* Improve documentation content and organization

- Update main page alert features to match README with better descriptions
- Revamp architecture page with detailed component explanations and data flow
- Add links to Pro Features and pricing in Open Source vs SaaS comparison
- Add community tutorial by Naren P on Kubernetes monitoring automation
diff --git a/docs/community-tutorials.rst b/docs/community-tutorials.rst
@@ -10,4 +10,5 @@ Here are more tutorials from the Robusta community:
 * **Video:** `Twitter challenge - Robusta.dev on 10 nodes <https://www.youtube.com/watch?v=l_zaCaY_wls>`_ by `Nuno Captain Corsair <https://twitter.com/nunixtech>`_
 * `Getting Started with Robusta on Digital Ocean <https://dev.to/heyrutam/getting-started-with-robusta-on-digital-ocean-3g41>`_ by `Rutam Prita Mishra <https://github.com/Rutam21>`_
 * `Getting Started with Robusta on Civo Cloud <https://dev.to/heyrutam/getting-started-with-robusta-on-civo-cloud-5h8f>`_ by `Rutam Prita Mishra <https://github.com/Rutam21>`_
-* `Kubernetes troubleshooting and automation using Robusta <https://xxradar.medium.com/kubernetes-troubleshooting-and-automation-using-robusta-13f113fcdc36>`_ by `Philippe Bogaerts <https://twitter.com/xxradar>`_
+* `Kubernetes troubleshooting and automation using Robusta <https://xxradar.medium.com/kubernetes-troubleshooting-and-automation-using-robusta-13f113fcdc36>`_ by `Philippe Bogaerts <https://twitter.com/xxradar>`_
+* `Enhancing Kubernetes Monitoring Automation with Robusta <https://naren4b.hashnode.dev/enhancing-kubernetes-monitoring-automation-with-robusta>`_ by `Naren P <https://naren4b.hashnode.dev/>`_
diff --git a/docs/how-it-works/architecture.rst b/docs/how-it-works/architecture.rst
@@ -1,40 +1,56 @@
 Architecture
 ==================
 
-The base installation for Robusta runs in-cluster as two Kubernetes deployments
+Robusta follows a modular architecture designed to integrate seamlessly with your existing Kubernetes observability stack. The system consists of core components that run in-cluster and optional components for enhanced functionality.
 
-* robusta-forwarder - Connects to the APIServer and monitors Kubernetes changes. Forwards them to robusta-runner.
-* robusta-runner - Receives all events, evaluates playbooks, sends notifications
+Core Components
+^^^^^^^^^^^^^^^
+
+Robusta's core architecture runs entirely within your Kubernetes cluster:
+
+**robusta-forwarder**
+  A lightweight deployment that connects to the Kubernetes APIServer to monitor cluster events and resource changes. It forwards relevant events to the runner component for processing. This component ensures Robusta stays up-to-date with your cluster state in real-time.
+
+**robusta-runner** 
+  The main processing engine that receives events from the forwarder, evaluates playbook rules, executes enrichment actions, and sends notifications to configured destinations. It contains the business logic for alert correlation, data enrichment, and routing decisions.
 
 .. image:: ../images/arch-1/arch-1.png
    :width: 600
    :align: center
 
-Optionally, Robusta has some additional components, described below.
+Data Flow
+^^^^^^^^^
 
-HolmesGPT (Optional)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Robusta's next generation AI-engine that investigates alerts automatically. See :ref:`AI Analysis <AI Analysis>`.
+1. **Event Collection**: The forwarder monitors Kubernetes APIServer for resource changes and forwards them to the runner
+2. **Alert Processing**: Prometheus AlertManager webhooks are received by the runner for alert enrichment
+3. **Playbook Execution**: The runner evaluates configured playbooks and triggers appropriate actions
+4. **Enrichment**: Additional context is gathered (logs, metrics, resource states) and attached to alerts
+5. **Routing**: Enriched alerts are routed to configured sinks (Slack, Teams, etc.) based on routing rules
 
-Bundled Prometheus (Optional)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Extended Architecture
+^^^^^^^^^^^^^^^^^^^^
 
-Install Robusta with :ref:`Prometheus included <embedded Prometheus stack>`. This is powered by ``kube-prometheus-stack``.
+**AI Analysis with HolmesGPT**
+  Robusta's AI engine automatically investigates alerts by analyzing logs, events, and cluster state to provide root cause analysis and remediation suggestions. See :ref:`AI Analysis <AI Analysis>` for configuration details.
 
-Alternatively, you can :ref:`integrate an existing Prometheus with Robusta <Integrating with Prometheus>`.
+**Prometheus Integration**
+  Robusta can work with your existing Prometheus setup or be installed with a :ref:`bundled Prometheus stack <embedded Prometheus stack>` powered by ``kube-prometheus-stack``. The integration enables automatic alert enrichment and correlation.
 
-Web UI (Optional)
-^^^^^^^^^^^^^^^^^^^^^^
+**Centralized Management**
+  The Robusta `SaaS platform <http://home.robusta.dev/?from=docs>`_ provides centralized alert management, historical analysis, and cross-cluster visibility. Self-hosted options are available for enterprise deployments.
 
-The Robusta `SaaS platform <http://home.robusta.dev/?from=docs>`_ provides a single pane of glass for all your alerts and clusters.
+**CLI Tooling**
+  The ``robusta`` CLI simplifies installation and configuration management by auto-generating Helm values and providing cluster diagnostics.
 
-On commercial plans, the UI is available for self-hosting in your own environment.
+Security & Networking
+^^^^^^^^^^^^^^^^^^^^^
 
-CLI (Optional)
-^^^^^^^^^^^^^^^^
-The ``robusta`` cli makes it easier to install Robusta by auto-generating Helm values.
+* All core components run within your cluster with configurable RBAC permissions.
+* External integrations use secure webhook endpoints with optional authentication.
+* SaaS connectivity is outbound-only with no inbound access required.
+* All data remains in your cluster unless explicitly sent to configured sinks e.g. Slack, Robusta UI.
 
 Next Steps
-^^^^^^^^^^^^^
+^^^^^^^^^^
 
 :ref:`Ready to install Robusta? Get started. <install>`
diff --git a/docs/how-it-works/oss-vs-saas.rst b/docs/how-it-works/oss-vs-saas.rst
@@ -4,12 +4,12 @@ Open Source vs SaaS
 Robusta has three deployment options:
 
 - **Open Source**: MIT-licensed engine that sends alerts to Slack, Teams, etc. No web UI.
-- **SaaS**: Open source engine + hosted web UI with additional features.
+- **SaaS**: Open source engine + hosted web UI with :doc:`additional features <../configuration/exporting/robusta-pro-features>`.
 - **Self-hosted**: Open source engine + on-premise web UI (enterprise plans).
 
 **Which should I choose?**
 
-Most teams use the SaaS option for the complete feature set without infrastructure overhead. The open source version works well if you only need basic alert routing to external systems.
+Most teams use the SaaS option for the :doc:`complete feature set <../configuration/exporting/robusta-pro-features>` without infrastructure overhead. The open source version works well if you only need basic alert routing to external systems.
 
 Pricing
 ^^^^^^^^^^^^
@@ -18,3 +18,8 @@ The Robusta OSS is and always will be free. It is MIT licensed.
 The Robusta UI is `free to get started <https://home.robusta.dev/pricing>`_ on our SaaS platform. If you want to self-host the UI, you'll need an enterprise plan.
 
 Contact support@robusta.dev for questions.
+
+Learn More
+^^^^^^^^^^^^
+- :doc:`Robusta Pro Features <../configuration/exporting/robusta-pro-features>` - Detailed breakdown of SaaS and enterprise features
+- `Pricing Plans <https://home.robusta.dev/pricing>`_ - Compare pricing options and start a free trial
diff --git a/docs/index.rst b/docs/index.rst
@@ -87,11 +87,11 @@ Robusta transforms basic Prometheus alerts into actionable insights with full Ku
 
         **How Robusta Improves Alerts:**
 
-        * **Auto-investigate** - Correlate alerts with logs and events
-        * **AI analysis** - Root causes and remediation steps  
-        * **Smart routing** - Route based on context
-        * **Self-healing** - Automatic remediation rules
-        * **Change tracking** - Correlate alerts with deployments
+        * **Self-Healing** - Define auto-remediation rules for faster fixes
+        * **Smart Grouping** - Reduce notification spam
+        * **AI Investigation** - Kickstart alert investigation with AI
+        * **Alert Enrichment** - Pod logs, events and more alongside alerts
+        * **Advanced Routing** - Based on team, namespace, and more
 
         Connect to your existing Prometheus or install our all-in-one bundle (based on kube-prometheus-stack). Need to go beyond Kubernetes? `Try Robusta Pro <https://home.robusta.dev>`_.
 
