From 21ebbb131d97e09b7379ad5cc60ebcfdec17e651 Mon Sep 17 00:00:00 2001
From: Hannah Hunter <hannahhunter@microsoft.com>
Date: Tue, 28 May 2024 16:50:02 -0400
Subject: [PATCH] update content in overview

Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com>
---
 .../distributed-scheduler-overview.md         | 55 ++++++++++++-------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/daprdocs/content/en/developing-applications/building-blocks/distributed-scheduler/distributed-scheduler-overview.md b/daprdocs/content/en/developing-applications/building-blocks/distributed-scheduler/distributed-scheduler-overview.md
index 3fdbf8d8e..88038ef84 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/distributed-scheduler/distributed-scheduler-overview.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/distributed-scheduler/distributed-scheduler-overview.md
@@ -6,7 +6,25 @@ weight: 1000
 description: "Overview of the distributed scheduler API building block"
 ---
 
+The Distributed Scheduler API works as an orchestrator for scheduling jobs in the future,  either at a specific time or a specific interval. The scheduler helps you with jobs like:
 
+- Scalable actor reminders
+- Scheduling any Dapr API to run at specific times or intervals, like when:
+  - Sending pub/sub messages
+  - Calling service invocations and input bindings
+  - Saving state to a state store 
+
+The Distributed Scheduler consists of two parts that work together to seamlessly schedule jobs across all of Dapr's API building blocks:
+- The Distributed Scheduler building block
+- [The Distributed Scheduler control plane service]({{< ref scheduler.md >}})
+
+This article covers the Distributed Scheduler API building block.
+
+## How it works
+
+The Scheduler building block is a job orchestrator, not executor. The design guarantees *at least once* job execution with a bias towards durability and horizontal scaling over precision. This means:
+- **Guaranteed:** A job is never invoked *before* the schedule is due.
+- **Not guaranteed:** A ceiling time on when the job is invoked *after* the due time is reached.
 
 <!-- 
 Include a diagram or image, if possible. 
@@ -16,35 +34,30 @@ Include a diagram or image, if possible.
 
 ### Delayed pub/sub
 
+The Distributed Scheduler building block enables you to delay your pub/sub messaging. You can publish a message in a future specific time -- for example, a week from today, or a specific UTC date/time.
+
 ### Scheduled service invocation
 
+The Distributed Scheduler building block provides the [service invocation]({{< ref service-invocation-overview.md >}}) building block with an orchestrator that schedules method calls between applications.
+
+### Schedule jobs across multiple replicas
+
+The Scheduler service enables the scheduling of jobs to scale across multiple replicas, while guaranteeing that a job is only triggered by 1 scheduler service instance.
+
 ### Actor reminders
 
+The [Dapr Workflow building block]({{< ref workflow-overview.md >}}) is built on top of Actor Reminders. The Distributed Scheduler building block improves the performance and scale of actor reminders, which present scale limitation issues. 
 
+### Store job details separately from user-associated data
 
-## Try out <concept>
+If a user would like to store their user associated data in a specific state store of their choosing, then they can provision a state store using the Dapr State Management Building Block and set `jobStateStore ` as `true` in the state store component’s metadata section. Having the `jobStateStore` set to `true` means that their user associate data will be stored in the state store of their choosing, but their job details will still be stored in the embedded etcd. If the `jobStateStore` is not configured, then the embedded etcd will be used to store both the job details and the user associated data.
 
-<!-- 
-If applicable, include a section with links to the related quickstart, how-to guides, or tutorials. --> 
+## Try out the Distributed Scheduler
 
-### Quickstarts and tutorials
-
-Want to put the Dapr <topic> API to the test? Walk through the following quickstart and tutorials to see <topic> in action:
-
-| Quickstart/tutorial | Description |
-| ------------------- | ----------- |
-| [<topic> quickstart](link) | Description of the quickstart. |
-| [<topic> tutorial](link) | Description of the tutorial. |
-
-### Start using <topic> directly in your app
-
-Want to skip the quickstarts? Not a problem. You can try out the <topic> building block directly in your application. After [Dapr is installed](link), you can begin using the <topic> API, starting with [the <topic> how-to guide](link).
-
-
--->
+You can try out the Distributed Scheduler building block directly in your application. After [Dapr is installed]({{< ref install-dapr-cli.md >}}), you can begin using the Distributed Scheduler API, starting with [the How-to: Set up a Scheduler guide]({{< ref howto-use-scheduler.md >}}).
 
 ## Next steps
 
-<!--
-Link to related pages and examples. For example, the related API spec, related building blocks, etc.
--->
+- [Learn how to use the distributed scheduler in your environment]({{< ref howto-use-scheduler.md >}})
+- [Learn more about the Scheduler control plane service]({{< ref scheduler.md >}})
+- [Distributed Scheduler API reference]({{< ref scheduler_api.md >}})