docs(guide): add guide for durable tasks vs DAG workflows

[BloggerBust]

Description

Adds a new guide: When to Use Durable Tasks vs. DAG Workflows.

This guide is intended to help readers choose the right Hatchet workflow pattern based on the structure and maintainability of the workflow they are building. It explains where DAGs are the natural fit, where durable tasks become the better choice, and where composing both models together makes sense.

The guide also includes:

• a practical workflow-evaluation exercise
• concrete examples and boundary cases
• a decision checklist
• links to the most relevant supporting docs

Type of change

• Documentation change (pure documentation change)

What's Changed

• Add a new guide at frontend/docs/pages/v1/durable-tasks-vs-dags.mdx
• Explain the distinction between DAG workflows and durable tasks as workflow authoring patterns
• Add guidance for when a DAG is the better fit
• Add guidance for when durable task composition is the better fit
• Add a practical step-by-step workflow evaluation exercise
• Add concrete examples, boundary cases, and a decision checklist
• Add internal links to related Hatchet docs
• Add the new guide to the v1 docs navigation in _meta.js

[vercel]

@BloggerBust is attempting to deploy a commit to the Hatchet Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hatchet-docs	Ready	Preview, Comment	Apr 23, 2026 5:46pm

[abelanger5]

@BloggerBust great, this looks very solid! Style-wise for these pages I think we want to be more direct, practical, and to the point, so the examples and overview are good but it's a bit wordy in other parts. I flagged the sections I felt could be cut down or stripped.

[abelanger5]

for this section, I think breaking up the text to include some mermaid diagrams/visuals rather than having three long blocks of text would be helpful!

[BloggerBust]

I shortened this section and added a mermaid diagram to the new Mixing both models section where I thought a visual would be more helpful.

[BloggerBust]

I ended up adding a Mermaid diagram here to make the point that branching grows beyond maintainability more clear. I kept it fairly simple, since Mermaid only gives me so much flexibility for showing branching that continues to fan out. The leaf labels end with ellipses to suggest that the diagram keeps expanding.

Here is a screenshot:

If you don’t think it quite works, I am happy to remove it. Another option would be to have your designer turn the idea into a custom diagram if you think the concept is worth illustrating but needs improvement.

[abelanger5]

I do like this, but I think it might be overwhelming given the complexity of the workflow we're showing. One potential solve is to place it into an accordion which is collapsed by default. But otherwise it might be helpful to show just a simple cycle in this diagram, since the immediate sentence before the diagram is That requires a cycle, which a DAG cannot express.

[BloggerBust]

@abelanger5 I updated the diagram to show a simpler agentic loop and laid it out horizontally so it takes up less vertical space and keeps the surrounding text in view. If you’re happy with this, I think the PR is ready to merge.

[abelanger5]

Nice! This is looking really good -- left two minor nits and a comment, but this should be good to merge.