Document differences in variables handling between Tasklist V1 and V2

[fabiopaini-camunda]

Tasklist V1 keeps track of completion-time snaphots of user task variables, while this is not supported in Tasklist V2. This can lead to counter-intuitive results when mixing the two APIs (using V2 to complete a task and V1 to query it).

This led to camunda/camunda#40231 to be opened as a bug. PM confirmed this is the expected behaviour, but it should still be properly documented in order to prevent other users from incurring in the same problem.

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
• This is already available but undocumented and should be released within a week. (add available & undocumented label)
• This is on a specific schedule and the assignee will coordinate a release with the Documentation team. (create draft PR and/or add hold label)
• This is part of a scheduled alpha or minor. (add alpha or minor label)
• There is no urgency with this change (add low prio label)

PR Checklist

• The commit history of this PR is cleaned up, using {type}(scope): {description} commit message(s)

• My changes are for an upcoming minor release and are in the /docs directory (version 8.9).
• My changes are for an already released minor and are in a /versioned_docs directory.

• I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
  • Engineering team review
  • Technical writer review via @camunda/tech-writers unless working with an embedded writer.

[christinaausley]

For the technical review, I clarified the semantic differences between Tasklist V1 and V2 variable handling, and focused on observable behavior rather than internal implementation. Also tightened the language around snapshots versus runtime state and added explicit guidance to avoid mixing APIs, so readers understand both the compatibility impact and the recommended migration approach 😄 Not sure if you want additional engineering review, but approving from a tech writer perspective. Thanks!

[fabiopaini-camunda]

@christinaausley thank you for the improvements, that looks perfect!