Update "Get started with human task orchestration" guide to include Play

[mesellings]

Description

Update the https://docs.camunda.io/docs/next/guides/orchestrate-human-tasks/ topic to include Play, milestone creation, and review as steps before running it on the cluster.

Relates to issue #4183.

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.

[mesellings]

@conceptualshark Don't worry, I'm going to rebase this and start again on Monday - I saw your changes, so I'll need to adapt the new stuff for this - don't spend any more time on it 😄

[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.6/.

• docs/guides/getting-started-orchestrate-human-tasks.md
• docs/guides/img/human-task-bpmn-diagram-gateway.png
• docs/guides/img/human-task-bpmn-diagram-tasks.png
• docs/guides/img/human-task-bpmn-diagram.png
• docs/guides/img/operate-open-tasklist.png
• docs/guides/img/play-chicken-complete.png
• docs/guides/img/play-open-form.png
• docs/guides/img/play-operate.png
• docs/guides/img/play-play-button.png

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.

Content has changed considerably after a merge conflict, it didn't need a review at this point

[mesellings]

@HanselIdes I've gone through the SaaS section and incorporated all your feedback - please check you are happy with the new structure, and I will move onto the SM section.

https://preview.docs.camunda.cloud/pr-4401/docs/next/guides/orchestrate-human-tasks/

• I've condensed it into 3 stages: Step 1: Create and design a process, Step 2: Design and link a form, and Step 3: Run and validate your process.
• I think it might be good to keep the SaaS & Web Modeler / SM Camunda 8 Run & Desktop Modeler split as it covers multiple bases for users - what do you think?

p.s. Ignore the right-hand menu for now, as it is still affected by the unchanged SM content.

[HanselIdes]

The one thing that must be addressed is the inaccuracy between SaaS and SM. In this guide as it's written, SM represents local development (Desktop Modeler + C8 Run), not self-managed.

[HanselIdes]

Arguably, the append element option offers better discovery for automation options and fewer steps, combining step 2 and 4. @lmbateman / @nikku, do you think we should drive new users to use the append anything option?

[mesellings]

@HanselIdes I've made those changes now, and other than the Append element comments, this is probably good to go for a final review?

In summary, I changed language to Desktop/Web as suggested, added a context pad link, and removed some heading elements from the Desktop validate section to avoid them appearing in the right-hand TOC (until we can fix this so it takes tabbed content into context).

[HanselIdes]

LGTM!

[HanselIdes]

Web Modeler Self-Managed is excluded, but that's appropriate for this stage of the journey

[conceptualshark]

My lingering question here is why the addition of Play changes the Web Modeler section of this guide into "validate with Play" as the end result, and not completing and checking on the task in Tasklist and Operate.

I don't think this guide should solely walk a user through building a model and using Play for initial validation. Presenting options for understanding how that process moves through/works with Operate and Tasklist is an equally important end result.

[conceptualshark]

Would it be beneficial for these to read more descriptively/match the description above? "SaaS and Web Modeler" | "Self-Managed and Desktop Modeler". As labels, they're short enough to scroll by right now, and if SaaS vs SM didn't entirely capture the paths here, I don't think Desktop vs Web does either.

Per Eric's point, I don't want the implication to be that these are exclusive methods for either version, but I do think we should align with the current Getting Started experience defining SaaS and SM as the modes of moving through the guides.

[conceptualshark]

I like the later wording of "route (a) process flow based on a user decision." "A human in the loop" still feels ambiguous; not blocking, but I'm not sure if a more descriptive task here would be helpful, though we describe the action enough otherwise so it may just be me.

[conceptualshark]

Suggested change

	Start by creating and designing a process to demonstrate how to route the process flow based on a user decision. In this example, you will create a process to decide what to eat for dinner.
	To learn how to route a process flow based on a user decision, you will create and design a process to decide what to eat for dinner.

[conceptualshark]

Context pad is more useful for the SaaS/web modeler side of things and not the same experience in desktop. If this section is swapped to Append element instead (and the context pad reference removed), it brings it back in line with the Desktop experience and would remove the need for another set of split/tabbed content.

[HanselIdes]

My lingering question here is why the addition of Play changes the Web Modeler section of this guide into "validate with Play" as the end result, and not completing and checking on the task in Tasklist and Operate.

I don't think this guide should solely walk a user through building a model and using Play for initial validation. Presenting options for understanding how that process moves through/works with Operate and Tasklist is an equally important end result.

@conceptualshark The goal mentioned in the guide says:
"This guide introduces you to the basics of human task orchestration. You will create a simple process to decide on what to eat for dinner, and drive the process flow according to that decision."

The best way to "drive the process flow" is through Play. It requires no navigation, and the additional features that Tasklist has (assignee, priority, process visualization) are unnecessary and perhaps distracting. I think it makes sense to mention that you can also go through Operate and Tasklist, but it is not necessary to achieve the stated goal.

If you believe the "get started" guides should feature Operate and Tasklist, then we can talk about changing their goal. Within the PM team, the focus has been around getting to 'hello world'. When I learned Python scripting (which is my background- I'm not a pro dev here), "hello world" happens in the console within a second of writing or editing the code with as little context change as possible.

[mesellings]

@HanselIdes @conceptualshark Thanks for the discussion, I think we should see whether @volodymyr-melnykc has a preferred perspective on this as well for HTA.

@volodymyr-melnykc - if the main goal of the Getting started with HTA doc is to provide a quick introduction into integrating HTA into your processes, should the path for this (SaaS) be:

• Use Play to show how you can add and simulate using user task forms, and simply refer to using Tasklist & Operate.
  OR
• As per the Desktop Modeler & Camunda 8 Run path, show how to use Tasklist and Operate (and not Play).

From my perspective, this hinges around what type of guide this is meant to be - is it an exhaustive 'this is how to do it', or more of a worked example 'here is an overview of how you can do it' that aims to introduce the key concepts without making a new user open multiple applications to begin with (i.e. keeping it simple)? It sounds like the preferred path is to get to "Hello World" as quickly/easily as possible, in which case Play makes sense?

[conceptualshark]

As per the Desktop Modeler & Camunda 8 Run path, show how to use Tasklist and Operate (and not Play).

I don't think it shouldn't include Play - I think that the guide can exist in the way it's been rewritten, but as a "Human task orchestration" guide, there is value in also explaining the way information moves between Operate and Tasklist, not only performing validation. There are no other getting started guides that explore these skills, and it matches the structure of the "Human Workflow" Academy guide.

[volodymyr-melnykc]

@mesellings @conceptualshark @HanselIdes
I agree that it depends on the goal we want to achieve with this guide.

If the goal is to help users walkthrough and validate a designed process quickly, then showcasing it with Play would be the best.
If the goal is to educate users on building human-centric processes, then highlighting Tasklist and Operate is important. The user should know that Tasklist is the interface where the actual task review and completion happens, and Operate is the tool where the user can monitor the progress of the process.

In my opinion, this guide should be a foundation for educating users on building human-centric processes. This doesn't mean that it shouldn't mention Play, though a quick process walkthrough and validation is not a primary objective here.

[HanselIdes]

Hi @melanie-butcher, I'm bringing you into this conversation as the head of the rapid adoption product stream. I believe you own the getting started guides.

We need a decision about whether the purpose of the HTO Getting Started guide. Is it to:

• show the development process in Web Modeler + Play, and mention Tasklist and Operate
• show the production environment in Web Modeler + Tasklist + Operate, and only mention Play
  This is an important branch point, and we don't have alignment.

[akeller]

What is the status of this PR?

[mesellings]

@akeller Blocked currently as we await a decision on which way the HTO lead(s) want to go - Slack thread here: https://camunda.slack.com/archives/C0259E9ETNJ/p1730708865839529. I will give a nudge in the thread.

[christinaausley]

@mesellings is this now slated for 8.7?

[mesellings]

@mesellings is this now slated for 8.7?

Yes thanks @christinaausley , this was unblocked last week, so will bring it back into the pipeline for completion by/for 8.7

[github-actions]

The preview environment relating to the commit 9543cdf has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-4401/index.html

[akeller]

I don't see much progress on this PR, so I'm assuming it's not going out with alpha4. If this is incorrect, please be prepared to adjust it for the upcoming working mode change.

[akeller]

I'm visiting all 8.7 tagged items to make you aware of the working mode change.

Version 8.7: will be sourced from the /versioned_docs/version-8.7 folder; URL paths will look like /docs/8.7/path/to/doc/.

Please ensure your changes are in the right directory with respect to the version you want to update. Changes currently in this PR would only happen in 8.8. You may want to backport to 8.7.