Updated best-practices.mdx

Updated based on Edwin's comments

Author: SaraMiteva

contents/docs/workflows/best-practices.mdx

@@ -4,16 +4,23 @@ sidebar: Docs
 showTitle: true
 ---
 
+## Boundaries
+### Define clear triggers and avoid overlapping workflows
 
-## 1. Define clear triggers and avoid overlapping workflows
-
-Use a single well-defined trigger per workflow (e.g. “user sign-up”, “purchase completed”, or a webhook), so the logic is clear. PostHog defines that every workflow starts with a trigger and ends with an exit. 
+Use a single well-defined trigger per workflow (e.g. “user sign-up”, “purchase completed”, or a webhook), so the logic is clear. PostHog defines that every workflow starts with a trigger and end with an exit. 
 
 Avoid multiple workflows that respond to the same event and perform overlapping actions as this can cause duplicate messages or conflicting side-effects.
 
 If you really need multiple workflows on the same event, consider whether a single workflow with [audience splits](/docs/workflows/workflow-builder#audience-splits)/branching logic would serve better. 
 
-## 2. Limit complexity and keep logic as simple as possible
+### Minimize deduplication and side-effects
+
+Don’t duplicate workflows that do essentially the same thing under slightly different triggers, which increases the risk of duplicate messages, conflicting updates, or unexpected user experience. 
+
+Avoid side-effects where possible. For example, don’t rely too heavily on property updates or event triggers inside a workflow, treat automations as eventual side-effects, not core business logic.
+
+## Logic, branching, and timing
+### Limit complexity and keep logic as simple as possible
 
 Use minimal branching and splits. Complex branching can make workflows hard to reason about.
 
@@ -26,37 +33,40 @@ Use minimal branching and splits. Complex branching can make workflows hard to r
 
 If you find yourself duplicating logic across multiple workflows, consider refactoring: either unify into one workflow or extract repeated logic into reusable sub-workflows (if supported), or design event properties in a way that triggers workflows cleanly.
 
-## 3. Use delays and conditions responsibly
+### Use delays and conditions responsibly
 
 Use delay steps (e.g. “wait 2 days”) or conditional logic only when necessary. Overuse can lead to unpredictable states, e.g. if user attributes change during the delay, or if event data evolves. 
 
 Keep records/logs where possible, especially for later debugging (e.g. knowing that a user was “waiting in step N of workflow X”).
 
-## 4. Ensure messaging channels are properly configured and tested
+### Design for fallback and safe defaults
 
-Before sending emails or other messages, [set up and verify your channels](/docs/workflows/configure-channels). For email: configure "from" name, from-address, and DNS (SPF/DKIM) to avoid spam/folder issues. 
-
-Use templating and personalization carefully (e.g. with placeholders like `{{ person.name }}`), but also verify that placeholders resolve and avoid sending messages with unresolved variables. 
-
-If sending to external channels (e.g. Slack, SMS, webhooks), treat them as equally important as email: ensure you have fallback or error handling logic (e.g. when a webhook endpoint fails).
+For actions that send messages or update user data: ensure that if some data is missing (e.g. user email, user property) the workflow safely skips or uses defaults rather than failing or sending bad messages.
 
-## 5. Plan for maintainability: naming, versioning, cleanup
+<ProductScreenshot
+    imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/error_handling_28a45d2ecf.png"
+    imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/error_handling_28a45d2ecf.png"
+    alt="Error handling in workflows"
+    classes="rounded"
+/>
 
-Give workflows descriptive names like `welcome_email_on_signup`, `drip_7_day_followup`, etc. Avoid ambiguous names like `workflow1`. Version your workflows when you make significant logic changes, or at least document changes in a changelog, so you know which version ran when.
+## Testing setups and delivery
 
-When a workflow becomes obsolete (e.g. onboarding process changed, or a campaign ended), archive or delete it to avoid accidental triggering and reduce maintenance burden.
+### Ensure messaging channels are properly configured and tested
 
-## 6. Minimize duplication and side-effects
+Before sending emails or other messages, [set up and verify your channels](/docs/workflows/configure-channels). For email: configure "from" name, from-address, and DNS (SPF/DKIM) to avoid spam/folder issues. 
 
-Don’t duplicate workflows that do essentially the same thing under slightly different triggers, which increases the risk of duplicate messages, conflicting updates, or unexpected user experience. 
+Use templating and personalization carefully (e.g. with placeholders like `{{ person.name }}`), but also verify that placeholders resolve and avoid sending messages with unresolved variables. 
 
-Avoid side-effects where possible. For example, don’t rely too heavily on property updates or event triggers inside a workflow, treat automations as eventual side-effects, not core business logic.
+If sending to external channels (e.g. Slack, SMS, webhooks), treat them as equally important as email: ensure you have fallback or error handling logic (e.g. when a webhook endpoint fails).
 
-## 7. Test workflows in a safe environment or subset first (staging/small user group)
+### Test workflows in a safe environment or subset first (staging/small user group)
 
 Before a full rollout: test with internal users or a small percentage of real users. Monitor delivery (for emails/messages), event logs, user property updates, or other side-effects. Watch for unintended behavior: e.g. multiple emails, loops (if your workflow triggers events that retrigger the same workflow), or delays stacking up.
 
-## 8. Monitor and log
+## Observability and limits
+
+### Monitor and log
 
 Ensure that failures (e.g. email bounce, webhook error) are captured and surfaced. When facing a problem, check the “[Troubleshooting & FAQs](/docs/workflows/troubleshooting)” section for Workflows.
 
@@ -70,23 +80,27 @@ Periodically review metrics: how many messages sent, how many workflows triggere
     classes="rounded"
 />
 
-## 9. Be mindful of costs and rate limits
+### Be mindful of costs and rate limits
 
 PostHog plans to price Workflows based on the number of real-time destinations and monthly messages after beta. Design workflows to minimize unnecessary messages. For example, avoid sending multiple messages to the same user around the same event, and use batching or deduplication logic where possible. 
 
 Clean up unused/outdated workflows to reduce unnecessary triggers and costs.
 
-## 10. Document workflows: what they do, why they exist, who owns them
+## Maintainability
+
+### Plan for maintainability: naming, versioning, cleanup
+
+Give workflows descriptive names like `welcome_email_on_signup`, `drip_7_day_followup`, etc. Avoid ambiguous names like `workflow1`. Version your workflows when you make significant logic changes, or at least document changes in a changelog, so you know which version ran when.
+
+When a workflow becomes obsolete (e.g. onboarding process changed, or a campaign ended), archive or delete it to avoid accidental triggering and reduce maintenance burden.
+
+### Document workflows: what they do, why they exist, who owns them
 
 For each workflow, maintain a short description: what triggers it, what it does, expected behavior, and owner/maintainer. Document assumptions (e.g. “this workflow only runs for paid users”, “email template X must exist”, “delay step must be at least 24h”). Onboard new team members with a “workflow map,” a high-level overview of all active workflows and their purposes.
 
-## 11. Design for fallback and safe defaults
 
-For actions that send messages or update user data: ensure that if some data is missing (e.g. user email, user property) the workflow safely skips or uses defaults rather than failing or sending bad messages.
 
-<ProductScreenshot
-    imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/error_handling_28a45d2ecf.png"
-    imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/error_handling_28a45d2ecf.png"
-    alt="Error handling in workflows"
-    classes="rounded"
-/>
+
+
+
+