Documentation fixes (#3268)

Author: juliusgeo

frontend/docs/pages/v1/external-events/event-filters.mdx

@@ -52,14 +52,12 @@ You also can create event filters by using the `filters` clients on the SDKs:
 </UniversalTabs>
 
 <Callout type="warning">
-  Note the `scope` argument to the filter. When you create a filter, it must be
-  given a `scope` which will be used by Hatchet internally to look it up. When
-  you push events that you want filtered, you **must provide a `scope` with
-  those events that matches the scope sent with the filter**. If you do not, the
-  filter will not apply.
+  Note the `scope` argument to the filter is required **both when creating a
+  filter, and when pushing events**. If the scope on filter creation does not
+  match the scope provided when pushing events, the filter will not apply.
 </Callout>
 
-Then, push an event that uses the filter to determine whether or not to run. For instance, this run will be skipped, since the payload does not match the expression:
+Then, push an event that uses the filter to determine whether to run. For instance, this run will be skipped, since the payload does not match the expression:
 
 <UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]} variant="hidden">
   <Tabs.Tab title="Python">

frontend/docs/pages/v1/external-events/index.mdx

@@ -6,6 +6,8 @@ description: Push events and trigger tasks from external sources.
 # External Events
 
 Integrate external event sources to trigger and coordinate tasks.
+For example, you could execute any number of tasks in response to a user signup by
+declaring the "user:signup" event type as triggers to each of the tasks, and then pushing an event when a user signs up.
 
 - [Pushing Events](/v1/external-events/pushing-events) — Send events to Hatchet
 - [Event Trigger](/v1/external-events/run-on-event) — Trigger tasks on events

frontend/docs/pages/v1/inter-service-triggering.mdx

@@ -5,7 +5,8 @@ import { snippets } from "@/lib/generated/snippets";
 
 ## Invoking Tasks From Other Services
 
-While Hatchet recommends importing your workflows and standalone tasks directly to use for triggering runs, this only works in a monorepo or similar setups where you have access to those objects. However, it's common to have a polyrepo, have code written in multiple languages, or otherwise not be able to import your workflows and standalone tasks directly. Hatchet provides first-class, type-safe support for handling these cases as well, with only minor code duplication, to allow you to trigger your tasks from anywhere in a type-safe way.
+While Hatchet recommends importing your workflows and standalone tasks directly to use for triggering runs, this only works in a monorepo or similar setups where you have access to those objects. However, it's common to have a polyrepo, have code written in multiple languages, or otherwise not be able to import your workflows and standalone tasks directly.
+Hatchet provides stub tasks for these cases, allowing you to trigger your tasks from anywhere in a type-safe way with only minor code duplication.
 
 ### Creating a "Stub" Task on your External Service (Recommended)
 
@@ -30,7 +31,7 @@ Consider a task with an implementation like this:
 
 <Snippet src={snippets.python.stubs.implementation.all} />
 
-To trigger this task from a separate service, for instance, in a microservices architecture, where the code is not shared, start by defining models that match the input and output types of the task defined above.
+To trigger this task from a separate service where the code is not shared, start by defining models that match the input and output types of the task defined above.
 
 <Snippet src={snippets.python.stubs.stub_trigger.define_models} />
 

frontend/docs/pages/v1/retry-policies.mdx

@@ -44,15 +44,17 @@ To enable retries for a task, simply add the `retries` property to the task obje
 
 You can add the `retries` property to any task, and Hatchet will handle the retry logic automatically.
 
-It's important to note that task-level retries are not suitable for all types of failures. For example, if a task fails due to a programming error or an invalid configuration, retrying the task will likely not resolve the issue. In these cases, you should fix the underlying problem in your code or configuration rather than relying on retries.
+It's important to note that task-level retries are not suitable for all types of failures.
+For example, if a task fails due to a programming error or an invalid configuration, retrying the task will likely not resolve the issue.
+In these cases, you should fix the underlying problem in your code or configuration rather than relying on retries. See [Bypassing retry logic](#bypassing-retry-logic).
 
 Additionally, if a task interacts with external services or databases, you should ensure that the operation is idempotent (i.e. can be safely repeated without changing the result) before enabling retries. Otherwise, retrying the task could lead to unintended side effects or inconsistencies in your data.
 
 ## Accessing the Retry Count in a Running Task
 
-If you need to access the current retry count within a task, you can use the `retryCount` method available in the task context:
+You can access the current retry count on the task's context object:
 
-<UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]} variant="hidden">
+<UniversalTabs items={["Python", "Typescript", "Go", "Ruby"]}>
   <Tabs.Tab>
     <Snippet src={snippets.python.retries.worker.retries_with_count} />
   </Tabs.Tab>
@@ -214,4 +216,4 @@ Python SDK client retries use exponential backoff with jitter. Fine-grained back
 
 Hatchet's task-level retry feature is a simple and effective way to handle transient failures in your tasks, improving the reliability and resilience of your tasks. By specifying the number of retries for each task, you can ensure that your tasks can recover from temporary issues without requiring complex error handling logic.
 
-Remember to use retries judiciously and only for tasks that are idempotent and can safely be repeated. For more advanced retry strategies, such as exponential backoff or circuit breaking, stay tuned for future updates to Hatchet's retry capabilities.
+Remember to use retries judiciously and only for tasks that are idempotent. For more advanced retry strategies, such as exponential backoff or circuit breaking, stay tuned for future updates to Hatchet's retry capabilities.

frontend/docs/pages/v1/timeouts.mdx

@@ -61,18 +61,18 @@ In these tasks, both timeouts are specified, meaning:
 2. If the task does not complete before the `execution_timeout` is reached (after starting), it will be cancelled.
 
 <Callout type="warning">
-  A timed out step does not guarantee that the step will be stopped immediately.
-  The step will be stopped as soon as the worker is able to stop the step. See
+  A timed out task does not guarantee that the task will be stopped immediately.
+  The task will be stopped as soon as the worker is able to stop the task. See
   [cancellation](./cancellation.mdx) for more information.
 </Callout>
 
 ## Refreshing Timeouts
 
-In some cases, you may need to extend the timeout for a step while it is running. This can be done using the `refreshTimeout` method provided by the step context (`ctx`).
+In some cases, you may need to extend the timeout for a task while it is running. This can be done by using the task context.
 
 For example:
 
-<UniversalTabs items={['Python', 'Typescript', 'Go', "Ruby"]} variant="hidden">
+<UniversalTabs items={['Python', 'Typescript', 'Go', "Ruby"]}>
   <Tabs.Tab>
   <Snippet src={snippets.python.timeout.worker.refresh_timeout} />
 
@@ -88,19 +88,6 @@ For example:
   </Tabs.Tab>
 </UniversalTabs>
 
-In this example, the step initially would exceed its execution timeout. But before it does, we call the `refreshTimeout` method, which extends the timeout and allows it to complete. Importantly, refreshing a timeout is an additive operation - the new timeout is added to the existing timeout. So for instance, if the task originally had a timeout of `30s` and we call `refreshTimeout("15s")`, the new timeout will be `45s`.
-
-The `refreshTimeout` function can be called multiple times within a step to further extend the timeout as needed.
-
-## Use Cases
-
-Timeouts are useful in a variety of scenarios:
-
-- Ensuring tasks don't run indefinitely and consume unnecessary resources
-- Failing tasks early if a critical step takes too long
-- Keeping tasks responsive by ensuring individual steps complete in a timely manner
-- Preventing infinite loops or hung processes from blocking the entire system
-
-For example, if you have a task that makes an external API call, you may want to set a timeout to ensure the task fails quickly if the API is unresponsive, rather than waiting indefinitely.
+In this example, the task initially would exceed its execution timeout. But before it does, we call the `refreshTimeout` method, which extends the timeout and allows it to complete. Importantly, refreshing a timeout is an additive operation - the new timeout is added to the existing timeout. So for instance, if the task originally had a timeout of `30s` and we call `refreshTimeout("15s")`, the new timeout will be `45s`.
 
-By carefully considering timeouts for your tasks and steps, you can build more resilient and responsive systems with Hatchet.
+The task timeout can be refreshed multiple times within a task to further extend the timeout as needed.