Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Moved technical details of Jobs implementation out of How To docs #4500

Open
wants to merge 11 commits into
base: v1.15
Choose a base branch
from

Conversation

WhitWaldo
Copy link
Contributor

Thank you for helping make the Dapr documentation better!

Please follow this checklist before submitting:

  • Commits are signed with Developer Certificate of Origin (DCO - learn more)
  • Read the contribution guide
  • Commands include options for Linux, MacOS, and Windows within codetabs
  • New file and folder names are globally unique
  • Page references use shortcodes instead of markdown or URL links
  • Images use HTML style and have alternative text
  • Places where multiple code/command options are given have codetabs

In addition, please fill out the following to help reviewers understand this pull request:

Description

The How-To docs typically are expected to contain SDK-specific implementation examples, but in the case of Jobs, the Go codetab contains a lot of technical detail that's extraneous to implementing the example given. This PR pulls those details out into a separate page.

I also scoured all the responses to queries about Jobs from Discord since the Jobs channel was created and included notes about those answers so they're more publicly accessible.

Issue reference

Please reference the issue this PR will close: #4498

… To page and into a separate one

Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
@WhitWaldo WhitWaldo requested review from a team as code owners January 22, 2025 13:47
@hhunter-ms hhunter-ms added this to the 1.15 milestone Jan 22, 2025
Copy link
Collaborator

@hhunter-ms hhunter-ms left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for starting this!

- Schedule: When the job triggers occur
- RepeatCount: An optional value indicating how often the job should repeat
- DueTime: An optional point in time representing either the one time when the job should execute (if not recurring)
or the start join from which the schedule should take effect
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
or the start join from which the schedule should take effect

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reworded this for better clarity

WhitWaldo and others added 8 commits January 22, 2025 21:00
…bs/jobs-features-concepts.md

Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
…bs/jobs-features-concepts.md

Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
…bs/jobs-features-concepts.md

Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
Copy link
Collaborator

@hhunter-ms hhunter-ms left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

quick 2nd review

---

Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive
into the features and concepts included with the Dapr Jobs engine and SDKs. Dapr Jobs:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
into the features and concepts included with the Dapr Jobs engine and SDKs. Dapr Jobs:
into the features and concepts included with the Dapr Scheduler service and SDKs. Dapr Jobs:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Scheduler service is an internal implementation detail. While it's an integral part of the Jobs capability, is that something we want to get into in a document that's sharing information about the publicly facing aspects of the Jobs functionality (which may be less subject to change than the internal bits)?

description: "Learn more about the Dapr Jobs features and concepts"
---

Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Now that you've learned about the [jobs building block]({{< ref jobs-overview.md >}}) at a high level, let's deep dive
Now that you've learned about the [jobs API building block]({{< ref jobs-overview.md >}}), let's dive

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm inclined to argue that we shouldn't be calling it the Jobs API building block (though it's called this in other existing Jobs documentation and on other concepts as well). I'd like to make the case for cleanly separating the two.

We have a Jobs building block and we have a Jobs API, but the API isn't the building block nor vice versa. The building block is the conceptual idea of the scheduling orchestrator and explains how the block is available for other capabilities to be built atop of (e.g. actor reminders and workflow timers), but the API describes the actual interfaces used for application development. The building blocks each have an API, but the API is a distinct thing from the conceptual blocks themselves.

They're distinct when we talk about Bindings:
image

...and Workflows:
image

...and Cryptography:
image

And then the other building blocks appear to confuse the two.

WhitWaldo and others added 2 commits January 23, 2025 18:10
…bs/jobs-features-concepts.md

Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
…bs/jobs-features-concepts.md

Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com>
Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants