workflows: review

Co-authored-by: Jun Lee <[email protected]>

Author: elithrar

src/content/docs/workers/runtime-apis/bindings/workflows.mdx

@@ -1,6 +1,6 @@
 ---
 pcx_content_type: navigation
-title: Vectorize
+title: Workflows
 external_link: /workflows/
 head: []
 description: APIs available in Cloudflare Workers to interact with

src/content/docs/workers/wrangler/commands.mdx

@@ -1258,9 +1258,9 @@ wrangler workflows list
 ```
 
 - `--page` <Type text="number" /> <MetaInfo text="optional" />
-  -  Show a sepecific page from the listing, can configure page size using "per-page"
+  -  Show a specific page from the listing. You can configure page size using "per-page".
 - `--per-page` <Type text="number" /> <MetaInfo text="optional" />
-  - Configure the maximum number of workflows to show per page.
+  - Configure the maximum number of Workflows to show per page.
 
 ### `instances`
 

src/content/docs/workflows/build/dynamic-steps.mdx

@@ -8,12 +8,12 @@ sidebar:
 
 A Workflow does not have to define all of its steps statically: steps can be created programmatically and/or conditionally.
 
-This allows you to not only trigger steps based on specific input parameters, but to also name steps dynamically, set the retry configuration for a step 
+This allows you to not only trigger steps based on specific input parameters, but to also name steps dynamically and set the retry configuration for a single step. 
 
 
 ## Example
 
-Steps can be created on-the-fly, allowing you create a step for each parameter passed to your Workflow, for each file you want to read from storage, or for calls to third-party APIs.
+You can create steps on-the-fly. You can create a step for each parameter passed to your Workflow, for each file you want to read from storage, or for calls to third-party APIs.
 
 For example, you can loop over each event, label the step dynamically, and have the step operate only over that `event`:
 

src/content/docs/workflows/build/events-and-parameters.mdx

@@ -10,11 +10,11 @@ When a Workflow is triggered, it can receive an optional event. This event can i
 
 Events are a powerful part of a Workflow, as you often want a Workflow to act on data. Because a given Workflow instance executes durably, events are a useful way to provide a Workflow with data that should be immutable (not changing) and/or represents data the Workflow needs to operate on at that point in time.
 
-## Passing parameters to a Workflow
+## Pass parameters to a Workflow
 
 You can pass parameters to a Workflow in two ways:
 
-* As an optional argument to the `create` method on a [Workflow binding] when triggering a Workflow from a Worker.
+* As an optional argument to the `create` method on a [Workflow binding](/workers/wrangler/commands/#trigger) when triggering a Workflow from a Worker.
 * Via the `--params` flag when using the `wrangler` CLI to trigger a Workflow.
 
 You can pass any JSON-serializable object as a parameter.
@@ -80,7 +80,7 @@ interface YourEventType {
 }
 ```
 
-When we pass our `YourEventType` to `WorkflowEvent` as a type parameter, the `event.payload` property now has the type `YourEventType` throughout our workflow definition:
+When you pass your `YourEventType` to `WorkflowEvent` as a type parameter, the `event.payload` property now has the type `YourEventType` throughout your workflow definition:
 
 ```ts title="src/index.ts"
 // Import the Workflow definition

src/content/docs/workflows/build/index.mdx

@@ -3,6 +3,8 @@ title: Build with Workflows
 pcx_content_type: navigation
 sidebar:
   order: 2
+  group:
+    hideIndex: true
 
 ---
 

src/content/docs/workflows/build/rules-of-workflows.mdx

@@ -5,16 +5,16 @@ sidebar:
   order: 10
 ---
 
-A Workflow contains one or more steps. Each step is a self-contained, individually retriable component of a Workflow. Steps may emit (optional) state that allows a Workflow to persist and continue from that step, even if a Workflow fails due to a network or infrastructure issue. A Workflow is comprised of one or more steps.
+A Workflow contains one or more steps. Each step is a self-contained, individually retriable component of a Workflow. Steps may emit (optional) state that allows a Workflow to persist and continue from that step, even if a Workflow fails due to a network or infrastructure issue.
 
 This is a small guidebook on how to build more resilient and correct Workflows.
 
 ### Ensure API/Binding calls are idempotent
 
 Because a step might be retried multiple times, your steps should (ideally) be idempotent. For context, idempotency is a logical property where the operation (in this case a step),
-can be applied multiple times without changing the result beyond the intial application.
+can be applied multiple times without changing the result beyond the initial application.
 
-As an example, let's assume you have a Workflow that charges your customers and you really don't want to charge them twice by accident, before charging them, you should
+As an example, let us assume you have a Workflow that charges your customers, and you really do not want to charge them twice by accident. Before charging them, you should
 check if they were already charged:
 
 ```ts
@@ -55,13 +55,13 @@ export class MyWorkflow extends WorkflowEntrypoint {
 
 :::note
 
-Guaranteeing idempotency might be optional in your specific use-case and implementation, although we recommend it to always try to guarantee it.
+Guaranteeing idempotency might be optional in your specific use-case and implementation, but we recommend that you always try to guarantee it.
 
 :::
 
 ### Make your steps granular
 
-Steps should be as self-contained as possible, this allows your own logic to be more durable in case of failures in third-party APIs, network errors, and so on.
+Steps should be as self-contained as possible. This allows your own logic to be more durable in case of failures in third-party APIs, network errors, and so on.
 
 You can also think of it as a transaction, or a unit of work.
 
@@ -85,12 +85,12 @@ export class MyWorkflow extends WorkflowEntrypoint {
 }
 ```
 
-Otherwise your entire workflow might not be as durable as you might think, and encounter into some undefined behaviour and you can avoid them by:
+Otherwise, your entire Workflow might not be as durable as you might think, and you may encounter some undefined behaviour. You can avoid them by following the rules below:
 
 - 🔴 Do not encapsulate your entire logic in one single step.
-- 🔴 Do not call seperate services in the same step (unless you need it to prove idempotency)
-- 🔴 Do not make too many service calls in the same step (unless you need it to prove idempotency)
-- 🔴 Do not do too much CPU-intensive work inside of a single step - sometimes engine might have to restart and it will start over from that step.
+- 🔴 Do not call separate services in the same step (unless you need it to prove idempotency).
+- 🔴 Do not make too many service calls in the same step (unless you need it to prove idempotency).
+- 🔴 Do not do too much CPU-intensive work inside a single step - sometimes the engine may have to restart, and it will start over from the beginning of that step.
 
 ```ts
 export class MyWorkflow extends WorkflowEntrypoint {
@@ -106,9 +106,9 @@ export class MyWorkflow extends WorkflowEntrypoint {
 }
 ```
 
-### Don't rely on state outside of a step
+### Do not rely on state outside of a step
 
-Workflows may hibernate and lose all in-memory state. This will happen when engine detects that there's no pending work and can hibernate until it needs to wake-up (because of a sleep, retry or event).
+Workflows may hibernate and lose all in-memory state. This will happen when engine detects that there is no pending work and can hibernate until it needs to wake-up (because of a sleep, retry, or event).
 
 This means that you should not store state outside of a step:
 
@@ -193,7 +193,7 @@ export class MyWorkflow extends WorkflowEntrypoint {
 }
 ```
 
-### Don't mutate your incoming events
+### Do not mutate your incoming events
 
 The `event` passed to your Workflow's `run` method is immutable: changes you make to the event are not persisted across steps and/or Workflow restarts.
 

src/content/docs/workflows/build/sleeping-and-retrying.mdx

@@ -8,7 +8,7 @@ sidebar:
 
 This guide details how to sleep a Workflow and/or configure retries for a Workflow step.
 
-## Sleeping
+## Sleep a Workflow
 
 You can set a Workflow to sleep as an explicit step, which can be useful when you want a Workflow to wait, schedule work ahead, or pause until an input or other external state is ready.
 
@@ -40,15 +40,15 @@ The second argument to `step.sleep` accepts both `number` (seconds) or a human-r
 
 ### Sleep until a fixed date
 
-Use `step.sleepUntil` to have a Workflow sleep to a specific `Date`: this can be useful when you have a timestamp from another system or want to "schedule" work to occur at a specific time (e.g. Sunday, 9AM UTC)
+Use `step.sleepUntil` to have a Workflow sleep to a specific `Date`: this can be useful when you have a timestamp from another system or want to "schedule" work to occur at a specific time (e.g. Sunday, 9AM UTC).
 
 ```ts
 // sleepUntil accepts a Date object as its second argument
 const workflowsLaunchDate = Date.parse("24 Oct 2024 13:00:00 UTC");
 await step.sleepUntil("sleep until X times out", workflowsLaunchDate)
 ```
 
-## Retrying steps
+## Retry steps
 
 Each call to `step.do` in a Workflow accepts an optional `StepConfig`, which allows you define the retry behaviour for that step.
 
@@ -70,7 +70,7 @@ When providing your own `StepConfig`, you can configure:
 * The total number of attempts to make for a step
 * The delay between attempts
 * What backoff algorithm to apply between each attempt: any of `constant`, `linear`, or `exponential`
-* When to timeout (in duration) before considering the step as failed (including during a retry attempt).
+* When to timeout (in duration) before considering the step as failed (including during a retry attempt)
 
 For example, to limit a step to 10 retries and have it apply an exponential delay (starting at 10 seconds) between each attempt, you would pass the following configuration as an optional object to `step.do`:
 

src/content/docs/workflows/build/trigger-workflows.mdx

@@ -8,7 +8,7 @@ sidebar:
 
 You can trigger Workflows both programmatically and via the Workflows APIs, including:
 
-1. With [Workers](/workers) via HTTP requests in a `fetch` handler or bindings from a `queue` or `scheduled` handler.
+1. With [Workers](/workers) via HTTP requests in a `fetch` handler, or bindings from a `queue` or `scheduled` handler
 2. Using the [Workflows REST API](/api/paths/accounts-account_id--workflows/get)
 2. Via the [wrangler CLI](/workers/wrangler/commands/#workflows) in your terminal
 
@@ -21,7 +21,7 @@ You can interact with a Workflow:
 * Directly over HTTP via the [`fetch`](/workers/runtime-apis/handlers/fetch/) handler
 * From a [Queue consumer](/queues/configuration/javascript-apis/#consumer) inside a `queue` handler
 * From a [Cron Trigger](/workers/configuration/cron-triggers/) inside a `scheduled` handler
-* Within a [Durable Object](/durable-objects/).
+* Within a [Durable Object](/durable-objects/)
 
 :::note
 
@@ -56,7 +56,7 @@ The following example shows how you can manage Workflows from within a Worker, i
 
 * Retrieving the status of an existing Workflow instance by its ID
 * Creating (triggering) a new Workflow instance
-* Returning the status of a given instance ID.
+* Returning the status of a given instance ID
 
 ```ts title="src/index.ts"
 interface Env {
@@ -93,7 +93,7 @@ export default {
 
 ### Inspect a Workflow's status
 
-You can inspect the status of any running Workflow instance by calling `status` against a specific instance ID. This allows you to programmatically inspect whether an instance is queued (waiting to be scheduled), actively running, paused or errored.
+You can inspect the status of any running Workflow instance by calling `status` against a specific instance ID. This allows you to programmatically inspect whether an instance is queued (waiting to be scheduled), actively running, paused, or errored.
 
 ```ts
 let instance = await env.MY_WORKFLOW.get("abc-123")
@@ -118,7 +118,7 @@ The possible values of status are as follows:
 };
 ```
 
-### Explicitly pausing a Workflow
+### Explicitly pause a Workflow
 
 You can explicitly pause a Workflow instance (and later resume it) by calling `pause` against a specific instance ID.
 
@@ -127,7 +127,7 @@ let instance = await env.MY_WORKFLOW.get("abc-123")
 await instance.pause() // Returns Promise<void>
 ```
 
-### Resuming a Workflow
+### Resume a Workflow
 
 You can resume a paused Workflow instance by calling `resume` against a specific instance ID.
 
@@ -138,7 +138,7 @@ await instance.resume() // Returns Promise<void>
 
 Calling `resume` on an instance that is not currently paused will have no effect.
 
-### Stopping a Workflow
+### Stop a Workflow
 
 You can stop a Workflow instance by calling `abort` against a specific instance ID.
 
@@ -149,7 +149,7 @@ await instance.abort() // Returns Promise<void>
 
 Once stopped, the Workflow instance *cannot* be resumed.
 
-### Restarting a Workflow
+### Restart a Workflow
 
 You can restart a Workflow instance by calling `restart` against a specific instance ID.
 

src/content/docs/workflows/build/workers-api.mdx

@@ -12,7 +12,7 @@ TODO
 
 TODO
 
-## Interacting with Workflows
+## Interact with Workflows
 
 * Running a Workflow with the `run()` method
 * `StepConfig`

src/content/docs/workflows/examples/index.mdx

@@ -5,6 +5,8 @@ pcx_content_type: navigation
 title: Examples
 sidebar:
   order: 6
+  group:
+    hideIndex: true
 
 ---