Docs should not recommend BPMN XML Editing the `zeebe:userTask` extension element

[falko]

This sentence gives me the impression that I have to manually edit the BPMN XML to set an extension property:

https://github.com/camunda/camunda-docs/blob/60178187659c87a71bb1377097ceba7a24ef3957/docs/components/modeler/bpmn/user-tasks/user-tasks.md?plain=1#L22-L23

While that is technically correct and probably describes exactly what Camunda engineers are doing when building & testing the engine, we must never give our users a feeling that manual XML editing is a valid option.

After searching for a while in the docs I found that the migration guide explains even with a screenshot that the Modeler has a dropdown in the property panel for that: https://github.com/camunda/camunda-docs/blob/60178187659c87a71bb1377097ceba7a24ef3957/versioned_docs/version-8.5/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks.md?plain=1#L174-L180

I'd hope that the Zeebe User Task will simply become the default in future versions, in which case the sentence should only inform about that.

[akeller]

@tmetzke, is there more context or perspective you can provide here? Can we link to the migration guide page to discourage manual editing on the BPMN XML?

[tmetzke]

We can probably refrain from actively stating "by adding ... element" and move to a wording that is more consistent with the business rule tasks:

https://github.com/camunda/camunda-docs/blob/60178187659c87a71bb1377097ceba7a24ef3957/docs/components/modeler/bpmn/business-rule-tasks/business-rule-tasks.md?plain=1#L32-L36

There, we also state which XML elements define whether this is a DMN- or job-based task. We neither mention a migration guide or modeler behavior there either. I think we should stay consistent in how we describe such elements with multiple implementation types.

Regarding default behavior, if I recall correctly, there have been extensive discussions on how to handle that moving forward. @aleksander-dytko might have more insights into that.

[aleksander-dytko]

I agree with @tmetzke - we might define that in more passive voice so that it's similar to other bpmn task types.

Regarding the Zeebe User Task - we want to deprecate the job-based approach with Camunda REST API V2 and then end support for it after an additional two releases.

[falko]

Yes, the language should make clear that it's just showing an implementation detail for reference and not give any impression that users have to write that XML code by hand. Instead of just passively describing the XML we could actively say that the Modeler will produce it.

[akeller]

There appears to be sufficient info in here now for a @camunda/tech-writers to pick up and add to their backlog. Moving ti to the DevEx board for one of them to pick up.

[tmetzke]

For transparency, I synced with @christinaausley here and my proposal for the Define a user task section would be the following:

A user task is marked as a **Zeebe user task** by the `zeebe:userTask` extension element. You can define assignments, scheduling, variable mappings, and a form for the user task as detailed in the following sections. Without the `zeebe:userTask` extension element, the user task behaves like a [service task](#job-worker-implementation).