docs: general improvements (#1881)

Co-authored-by: Tal <[email protected]>
Co-authored-by: Shahar Glazner <[email protected]>

docs/development/external-url.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Keep with Internet URL"
-sidebarTitle: "Keep with Internet URL"
+title: "Keep with an external URL"
+sidebarTitle: "Keep with an external URL"
 ---
 
 ## Introduction

docs/mint.json

@@ -32,8 +32,9 @@
       "group": "Overview",
       "pages": [
         "overview/introduction",
-        "overview/keyconcepts",
         "overview/usecases",
+        "overview/comparisons",
+        "overview/keyconcepts",
         "overview/ruleengine",
         "overview/presets",
         {
@@ -44,8 +45,7 @@
           ]
         },
         "overview/maintenance-windows",
-        "overview/examples",
-        "overview/comparison"
+        "overview/examples"
       ]
     },
     {

docs/overview/introduction.mdx

@@ -1,26 +1,26 @@
 ---
 title: "Introduction"
-description: "Keep is an open-source alert management and automation tool that provides everything you need to create and manage alerts effectively."
+description: "Keep is an open-source alert management and automation tool that provides everything you need to collect, enrich and manange alerts effectively."
 ---
-<Note>Start using Keep by logging in to the [platform](https://platform.keephq.dev).</Note>
+<Note> You can start using Keep by logging in to the [platform](https://platform.keephq.dev).</Note>
 
-## What's alert?
+## What's an alert?
 
 An alert is an event that is triggered when something undesirable occurs or is about to occur.
-It is usually triggered by monitoring tools such as Prometheus, Grafana, or CloudWatch, and in some cases, proprietary tools.
+It is usually triggered by monitoring tools such as Prometheus, Grafana, or CloudWatch, and some proprietary tools.
 
-Alerts usually categorized into three different groups:
+Alerts are usually categorized into three different groups:
 - Infrastructure-related alerts - e.g., a virtual machine consumes more than 99% CPU.
 - Application-related alerts - e.g., an endpoint starts returning 5XX status codes.
 - Business-related alerts - e.g., a drop in the number of sign-ins or purchases.
 
 ## What problem does Keep solve?
 Keep helps with every step of the alert lifecycle:
-1. Maintenance - Keep integrates with your tools, allowing you to manage all of your alerts within a single interface.
-2. Noise reduction - By integrating with monitoring tools, Keep can deduplicate and correlate alerts to reduce noise in your organization. Rule-based (all distributions), and AI-based (Keep Enterprise only).
-3. Automation - [Keep Workflows](/workflows) enable automated alert enrichment and response.
-4. Incident Correlation - Automatically assign alerts to incidents, automatic triaging and root cause analysis (Keep Enterprise only).
-5. Summarization - Summary of an incident based on past incidents and the knowledge base (Keep Enterprise only).
+1. Maintenance - Keep integrates with all of your monitoring tools, allowing you to manage all of your alerts within a single interface.
+2. Noise reduction - By integrating with monitoring tools, Keep can deduplicate and correlate alerts to reduce noise in your organization. There are 2 types of deduplication: Rule-based (all distributions), and AI-based (Keep Enterprise only).
+3. Automation - [Keep Workflows](/workflows) enables automated alert enrichment and response.
+4. Incident Correlation - Automatically assigns alerts to incidents, performs triage, and conducts root cause analysis (Keep Enterprise only).
+5. Summarization - Keep summarizes incidents based on past incidents and a knowledge base (Keep Enterprise only).
 
-## How does Keep integrate with the alerts?
+## How does Keep integrate with alerts?
 Alerts can either be [pulled](/platform/alerts#pulled-alerts) by Keep or [pushed](/platform/alerts#pushed-alerts) into it. Keep also offers zero-click alert instrumentation through [webhook installation](/platform/providers#webhook-integration).

docs/overview/keyconcepts.mdx

@@ -2,47 +2,48 @@
 title: "Key concepts"
 ---
 ## Alert
-Alert is an event that triggered when something bad happens or going to happen.
-The term "alert" can sometimes be interchanged with "alarm" (e.g. in CloudWatch) or "monitor" (e.g. in Datadog).
+An alert is an event that is triggered when something bad happens or going to happen.
+The term "alert" can sometimes be interchanged with "alarm" (e.g. in CloudWatch) or "monitor" (Datadog).
 
-You can easily initiate a [Workflow](#workflow) when an alert is triggered.
+## Incident
+An incident is a group of alerts that are related to each other.
 
 ## Provider
-A Provider serves as the building block for input/output in Keep.
+A provider can be a module that pulls alerts into Keep or pushes data out of keep by interacting with external systems.
 
 ### Provider as a data source
 Within the context of a Workflow, a Provider can:
-- Query data - query Datadog's API or runs a SQL query against a database.
+- Query data - query Datadog's API or run a SQL query against a database.
 - Push data - send a Slack message or create a PagerDuty incident.
 
 ### Provider as an alert source
 When you connect a Provider, Keep begins to read and process alerts from that Provider. For example, after connecting your Prometheus instance, you'll start seeing your Prometheus alerts in Keep.
 A Provider can either push alerts into Keep, or Keep can pull alerts from the Provider.
 
 #### Push alerts to Keep (Manual)
-Configure your alert source to push alerts to Keep.
+You can configure your alert source to push alerts into Keep.
 
 For example, consider Promethues. If you want to push alerts from Promethues to Keep, you'll need to configure Promethues Alertmanager to send the alerts to
-'https://api.keephq.dev/alerts/event/prometheus' using API key authentication. Each Provider implements Push mechanism and documented under the specific Provider page.
+'https://api.keephq.dev/alerts/event/prometheus' using API key authentication. Each Provider implements Push mechanism and is documented under the specific Provider page.
 
 #### Push alerts to Keep (Automatic)
-In compatible tools, Keep can automatically integrate with the alerting policy of the source and add itself as an alert destination. You can learn more about Webhook Integration [here](/platform/providers#webhook-integration).
-Please note that this will slightly modify your monitors/notification policy to include Keep.
+In compatible tools, Keep can automatically integrate with the alerting policy of the source tool and add itself as an alert destination. You can learn more about Webhook Integration [here](/platform/providers#webhook-integration).
+Please note that this will slightly modify your monitors/notification policy.
 
 ### Pull alerts by Keep
 Keep also integrates with the alert APIs of various tools and can automatically pull alerts. While pulling is easier to set up (requiring only credentials), pushing is preferable when automation is involved.
 
 ## Workflow
 Workflows consist of a list of [Steps](/workflows/overview#steps) and [Actions](/workflows/overview#actions).
 A workflow can be triggered in the following ways:
-- When Alert is triggered.
+- When an Alert is triggered.
 - In a predefined interval.
 - Manually.
 
 Workflows are commonly used to:
 1. Enrich your alerts with more context.
 2. Automate the response to alert.
-3. Create multi-steps alerts.
+3. Create multi-step alerts.
 
 ## API first
 Keep is an API-first platform, meaning that anything you can do via the UI can also be accomplished through the [API](/api-ref)

docs/overview/usecases.mdx

@@ -2,7 +2,7 @@
 title: "Use cases"
 ---
 
-## Central Alerts management
+## Central alert management
 No more navigating between multiple Prometheus instances and dealing with per-region, per-account CloudWatch settings.
 
 By linking your alert-triggering tools to Keep, you gain a centralized dashboard for managing all your alerts.
@@ -13,15 +13,14 @@ With Keep, you can review, throttle, mute, and fine-tune all of your alerts from
 ## Alerts enrichment
 You're no longer constrained by the alerting mechanisms implemented in your tools.
 
-Want alerts to be triggered solely for your enterprise customers? No problem.
-Want to include additional context not available in your current tools? Easy.
+Need alerts triggered exclusively for your enterprise customers? No problem. Want to add extra context that isn’t available in your existing tools? Easy.
 
 Simply connect your observability tools, databases, ticketing systems, or any other tools that can provide additional context, and integrate them with your alerts.
 
 ## Automate the alert response process
-The saying goes, "If you can automate the response to an alert, it shouldn't be an alert," right?
+There's a saying that goes, "If you can automate the response to an alert, it shouldn't be an alert," right?
 
-While that might hold true in an ideal world, we understand that many times the response to an alert can be automated—whether by double-checking or taking steps to verify that the alert is not a false positive.
+While that might be true in an ideal world, we understand that many times the response to an alert can be automated—whether by double-checking or taking steps to verify that an alert is not a false positive.
 
 Consider a common scenario—you receive a 502 error on one of your endpoints. That's alert-worthy, isn't it?