docs(concepts): Improve Execution Listener documentation

[ce-dmelnych]

Description

Relates to: camunda/camunda#16217

This PR improves the documentation for Execution Listeners. It builds on the initial documentation and received feedback to improve clarity and provide more comprehensive guidance for developers.

Scope:

• Added details about the blocking behavior of ELs
• Described how the system handles incidents raised during EL job or expression failures.
• Updated limitations section.
• Enhanced documentation structure and added references to relevant resources & code example.

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support.
• This is already available but undocumented and should be released within a week.
• This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
• This is part of a scheduled alpha or minor. (apply alpha or minor label)
• There is no urgency with this change and can be released at any time.

PR Checklist

• My changes are for an already released minor and are in /versioned_docs directory.
• My changes are for the next minor and are in /docs directory (aka /next/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

[github-actions]

👋 🤖 🤔 Hello! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.5/.

• docs/components/concepts/execution-listeners.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[ce-dmelnych]

Preview environment with update Execution Listeners page.

[tmetzke]

🚀 Thanks, @ce-dmelnych, that will help users understand listeners a lot better 👍

[mesellings]

@tmetzke I will do a review for you now 👍

[mesellings]

@ce-dmelnych I have completed the review and made commits directly into the branch:

• Edits for structure (headings, tables)
• Readability, active voice edits
• Style guide edits (for example, we do not use "e.g.", but rather "for example," or "such as")

Happy to approve, nice work! 👍

[mesellings]

@ce-dmelnych Would you like me to merge this?

[ce-dmelnych]

@mesellings Thank you for your efforts! The documentation looks great with your improvements 🎉

One small note: it might be better to present the text under Job execution failure and Expression evaluation failure headings as paragraphs instead of list items. Using items could potentially confuse users by making the explanations appear fragmented.

What do you think?

[mesellings]

@ce-dmelnych I would normally try and avoid very verbose paragraphs like this if I can (hence splitting the sentences into bullets) to avoid cognitive overload when reading, but as you know the subject matter better than I do, happy if you want to have these as paragraphs, but perhaps split the sentences on new lines?

For example:

If an execution listener job fails (for example, if an external service is unavailable), it is retried according to the retries property.

If all retries are exhausted and the job still fails, the process halts, and an incident is raised. Once the incident is resolved, only the listener with the failed job is retried, allowing the process to resume from the point of failure without re-executing successfully completed listeners.

[ce-dmelnych]

@mesellings Thanks for sharing your perspective!
I see your point about avoiding cognitive overload with long paragraphs. Splitting the sentences on new lines as you suggested could be a good compromise, making it easier to read without the potential confusion of bullet points as the items are tightly connected.

Let's go with the approach of using separate lines for clarity.

I appreciate your flexibility and input!

[mesellings]

@ce-dmelnych Sounds good! 👍

[mesellings]

@ce-dmelnych I still have the branch open, want me to make the changes quickly?

[ce-dmelnych]

@ce-dmelnych I still have the branch open, want me to make the changes quickly?

@mesellings
That would be great, thank you!

[mesellings]

@ce-dmelnych changes made, all good to go:

• Changed bullets to paras
• Removed superfluous line as now not needed

[mesellings]

Approved 👍

[mesellings]

@ce-dmelnych Are you happy for us to merge this now, or do you want to wait for next Mon/Tue?

[github-actions]

🧹 Preview environment for this PR has been torn down.

[ce-dmelnych]

@mesellings
I'm happy for it to be merged now, no need to wait. Thanks for checking!