Improve documentation of workflows and its steps #1020

tjeerddie · 2025-07-31T16:22:30Z

changed architecture workflows to explain everything without code, only referencing with links to docs with code.
add a page in getting started for workflows to explain how to create workflows, moving old docs from the architecture and beginner workshop.
add workflows page with the different types of workflow util functions in refence-docs/workflows folder.
add re-usable step and singledispatch code examples in refence-docs/workflows/workflow-steps

Todo's:

Related: #533

docs/architecture/application/workflow.md

docs/getting-started/workflows.md

docs/reference-docs/workflows/workflow-steps.md

mkdocs.yml

its included in the workflows page.

codspeed-hq · 2025-08-04T13:39:20Z

CodSpeed Performance Report

Merging #1020 will not alter performance

_{Comparing improve-workflow-documentation (3e983fc) with main (1818a0d)}

Summary

✅ 13 untouched benchmarks

codecov · 2025-08-04T13:40:15Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.93%. Comparing base (1818a0d) to head (3e983fc).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1020   +/-   ##
=======================================
  Coverage   84.93%   84.93%           
=======================================
  Files         214      214           
  Lines       10408    10408           
  Branches     1020     1020           
=======================================
  Hits         8840     8840           
  Misses       1295     1295           
  Partials      273      273

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Mark90

Nice work! Read most of it and have left a bunch of suggestions you can apply (or not) and a few questions

docs/architecture/application/workflow.md

docs/getting-started/base.md

docs/architecture/application/workflow.md

docs/reference-docs/workflows/workflow-steps.md

docs/reference-docs/workflows/workflows.md

docs/workshops/advanced/workflow-introduction.md

mkdocs.yml

docs/getting-started/workflows.md

Co-authored-by: Mark Moes <[email protected]>

- add workflow decorator to the workflow page in reference docs. - update workflow-introduction to reference the workflow architecture instead of having copy pasted text. - add empty line between headers and text. - use link definitions for long urls.

Mark90 · 2025-08-08T08:32:32Z

docs/getting-started/workflows.md

+- [terminate_workflow]
+- [validate_workflow]
+
+under the hood they all use a [workflow] decorator which can be used for tasks that don't fit any of the types above.


Suggested change

under the hood they all use a [workflow] decorator which can be used for tasks that don't fit any of the types above.

Under the hood they all use a [workflow] decorator which can be used for tasks that don't fit any of the types above.

Mark90 · 2025-08-08T08:41:30Z

docs/getting-started/workflows.md

+
+!!! example
+
+    for inspiration look at an example implementation of the [lazy workflow instances]


Suggested change

for inspiration look at an example implementation of the [lazy workflow instances]

For inspiration look at an example implementation of the [lazy workflow instances].

Mark90 · 2025-08-08T08:46:30Z

docs/getting-started/workflows.md

+
+For `@modify_workflow`, `@validate_workflow` and `@terminate_workflow` the `subscription` is directly usable from the first step.
+
+[Information about all usable step decorators can be found here](../architecture/application/workflow#workflow-steps)


Opinionized nit :) When the entire sentence is a link it becomes more difficult to spot - at least when using a light theme. The contrast between normal and clickable text helps it stand out for me.

Suggested change

[Information about all usable step decorators can be found here](../architecture/application/workflow#workflow-steps)

Information about all usable step decorators can be found on [the architecture page on workflows](../architecture/application/workflow#workflow-steps).

Mark90 · 2025-08-08T08:48:35Z

docs/getting-started/workflows.md

+Create a new empty database migration with the following command:
+
+```shell
+PYTHONPATH=. python main.py db revision --head data --message "add User and UserGroup workflows"


Think PYTHONPATH=. is a remnant from the past? I haven't had to use this in our own nor the example orchestrator. Imo it'd be better to have this in a troubleshooting section (if people indeed run into it) rather than prefixing it everywhere

Suggested change

PYTHONPATH=. python main.py db revision --head data --message "add User and UserGroup workflows"

python main.py db revision --head data --message "add User and UserGroup workflows"

Mark90 · 2025-08-08T08:49:41Z

docs/getting-started/workflows.md

+Run the migration with the following command:
+
+```shell
+PYTHONPATH=. python main.py db upgrade heads


Same suggestion as above

Suggested change

PYTHONPATH=. python main.py db upgrade heads

python main.py db upgrade heads

Mark90 · 2025-08-08T08:51:06Z

docs/reference-docs/workflows/workflow-steps.md

+    return {"response": response}
+```
+
+While this approach works, the switch logic (via match or if isinstance) can become unwieldy as more product types are introduced.


Suggested change

While this approach works, the switch logic (via match or if isinstance) can become unwieldy as more product types are introduced.

While this approach works, the switch logic (via `match` or `if isinstance()`) can become unwieldy as more product types are introduced.

Mark90

Left a few small remaining comments.

Amazing work! 🚀

tjeerddie marked this pull request as draft July 31, 2025 16:22