Docs for iterable job

[bmulholland]

I'm implementing my first iterable job and struggled a bit, so I thought I'd share some feedback on how the docs could be clearer.

1. ActiveRecord Relation Example: Iterating over an ActiveRecord relation seems like a common use case, but it took me 30 minutes of searching to find code examples. A simple example in the wiki would have helped me.
2. Confusion Around Job Arguments: The documentation isn’t clear on how arguments work when calling jobs. I spent a lot of time confused by cursor— whether I needed to pass it in as a starting arg, and if so what value to start with, or if Sidekiq handled it internally. I also took a while to figure out that the arguments also get passed to the iteration block, and the order that happened in was unintuitive. Also, it wasn't clear that the args is absolutely required to be included, even if you don't need it in the iteration block.
3. Keyword Args and JSON Constraints: Even though I’m aware of JSON argument constraints in Sidekiq, I made the mistake of adding another keyword argument alongside cursor, just because cursor is a kwarg. Clarity that cursor is a special inside param could have saved me time.
4. First Example Feels Overloaded: The existing “simple” example is actually quite complex — it schedules multiple parallel jobs in batches, which overwhelmed me, especially as the first example. I had questions like "is start_at a required field? Count?" It’s covering two concepts at once: parallel jobs and iteration. It would have been easier to understand if the docs started with a basic, linear iteration example and then following up with the more advanced parallel execution.

Combining these all together, perhaps the first example could instead be a simple version of ActiveRecord enumerator with a single argument, including an example of calling that job? This would have really saved me cognitive load.

[bmulholland]

Another: I'd read "Your job class must include the Sidekiq::IterableJob module, not Sidekiq::Job" as "you must not include Sidekiq::Job"

It looks like that's actually okay but then we just include Sidekiq::Job::Iterable. This is helpful because I can use the other tooling we've added in a base job class we inherit from, which includes Sidekiq::Job already.

[mperham]

Thanks for the feedback, we're still polishing bits.

The API is a bit confusing but I wanted to retain compatibility with the existing iteration gems/code out there so I couldn't change too much of the API.

Where did you start from that it took you 30 minutes to find the docs? The Iteration page is linked on the wiki home and in the 7.3.0 changelog.

[bmulholland]

Happy to help! Shared this as input to the polishing :)

I started from the wiki page, and even clicked on to open the source file linked. I think my eyes may have glazed over? I have no good explanation for not reading the comments there, but I did not. It's most likely that I just wasn't expecting the comments to include examples of how to use them. I won't rule out PEBKAC, though.