Hackathon #7817
Hackathon #7817
Conversation
|
👋 🤖 🤔 Hello, @alexronquillo! 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.8/.
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. |
| import Install from './react-components/\_install-c8run.md' | ||
|
|
||
| This guide is designed for users who prefer a low-code approach to process automation. You can follow this tutorial using either a local, Self-Managed lightweight setup, or Camunda 8 SaaS. | ||
| This tutorial introduces you to the basics of [human task orchestration](../reference/glossary.md#human-task) using either Camunda 8 Self-Managed or SaaS. |
There was a problem hiding this comment.
Two key IA changes:
- Use the now-standard approach of a single-sentence introduction.
- Clarify that this is a tutorial, not a guide.
| This tutorial introduces you to the basics of [human task orchestration](../reference/glossary.md#human-task) using either Camunda 8 Self-Managed or SaaS. | ||
|
|
||
| Camunda 8 allows you to orchestrate processes with human tasks of any complexity. Utilizing user tasks, you can create and assign tasks to users. Then, users can perform their work and enter the necessary data to drive the business process. | ||
| ## About |
There was a problem hiding this comment.
Add a proper "About" section.
| Camunda 8 allows you to orchestrate processes with human tasks of any complexity. Utilizing user tasks, you can create and assign tasks to users. Then, users can perform their work and enter the necessary data to drive the business process. | ||
| ## About | ||
|
|
||
| You will create a simple process to decide on dinner, and drive the process flow according to that decision. |
There was a problem hiding this comment.
Because this is a tutorial, the "About" section should tell the story of what the reader will build, so they have a clear view of the end-goal.
|
|
||
| You will create a simple process to decide on dinner, and drive the process flow according to that decision. | ||
|
|
||
| <img src={OperateHumanTasks} alt="Process instance monitoring in Operate" /> |
There was a problem hiding this comment.
Ideally, we would include the "end goal" BPMN diagram here. Due to lack of time, we used the closest screenshot we had.
|
The preview environment relating to the commit 473d4b9 has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-7817/ |
|
|
||
| <details> | ||
| <summary>Have you installed Camunda yet?</summary> | ||
| <Install/> |
There was a problem hiding this comment.
In the current version of this doc, we have a tab group with each tab consisting of a summary dropdown. The summary basically includes an entire guide within it. Instead, we considered running Camunda 8 in SaaS or Self-Managed a prerequisite to this guide. Therefore, we reorganized this section with links to guides to set that up first.
| - [Camunda 8 SaaS](/components/saas/saas.md). For example, [sign up for a free SaaS trial account](https://accounts.cloud.camunda.io/signup). | ||
| - [Camunda 8 Self-Managed](/self-managed/about-self-managed.md). For example, see [Run your first local project](../getting-started-example). | ||
|
|
||
| ## Step 1: Create a new process |
There was a problem hiding this comment.
On one hand, having step labels in the heading provides the reader some sense of progress. On the other hand, it makes headings more verbose. Considering the scrolling sidebar nav in Docusaurus also acts as a progress bar, we decided to remove this for now. This allow allows the steps to start with action verbs, empowering the reader to "do" something.
| :::note | ||
| By default, the Camunda Helm chart uses Bitnami open-source images. For production environments, Camunda recommends switching to vendor-supported enterprise images. This guide explains how to create registry secrets and install [Camunda with enterprise images](/self-managed/deployment/helm/configure/registry-and-images/install-bitnami-enterprise-images.md). | ||
| ::: | ||
| Install the Orchestration Cluster with Helm for testing and development. |
There was a problem hiding this comment.
Use the now-standard approach of a single-sentence introduction.
| ### Install and verify the deployment | ||
|
|
||
| Installing all components in a cluster requires downloading all related Docker images to the Kubernetes nodes. The time required depends on your cloud provider and network speed. | ||
| - A functioning Kubernetes cluster with: |
There was a problem hiding this comment.
Clean up the prerequisites section.
In the current doc, some of this content is scattered throughout the doc. In this version, we included it all in the prerequisites.
| Starting in 8.9-alpha3, the default secondary storage used by Camunda 8 Run and default Helm values is H2 for lightweight, out-of-the-box setups. Elasticsearch is still provided and supported as an optional alternative; OpenSearch is supported for Self‑Managed deployments but is not bundled in Camunda 8 Run. Enable the backend you require explicitly if you need full-featured search/analytics or to run existing Elasticsearch-backed Operate instances. | ||
| ::: | ||
|
|
||
| ## Full Cluster |
There was a problem hiding this comment.
One of the fundamental IA philosophies we discussed is: be opinionated. Many of our guides, including this one give the reader multiple options throughout the steps, leading to decision fatigue. We want to give users fewer ways (ideally one) to do something. If there are multiple ways, consider using another guide.
This is a "quick install" guide, akin to a "hello world" guide. So, to align with that philosophy, we opted to instruct the user to only install the OC without providing instructions for the rest of the cluster. We can consider moving this to another doc if it isn't already covered.
| #### 1. Set up port-forwarding | ||
|
|
||
| Open separate terminal windows and run these commands to access the required services: | ||
| 1. Create a namespace |
There was a problem hiding this comment.
The general structure we discussed for a guide step is:
- Tell the user what to do (instruction with action verb)
- Give the user the resources to do it, if necessary (for example, a code block)
- Tell the user what happened as a result and/or why they did it, if necessary
Leading with the instruction (1) keeps the reader moving with momentum, rather than stopping at the start of each step to gather context.
|
|
||
| You can still use localhost ports if you prefer traditional port-forwarding. Stop kubefwd with **Ctrl+C** when finished. Be aware kubefwd modifies your `/etc/hosts` temporarily; it restores the file when it exits. | ||
| ::: | ||
| This installs the latest version of the Helm chart, by default. If you need another version, [use the `--version` flag](https://helm.sh/docs/helm/helm_install/#options). |
There was a problem hiding this comment.
Before, we had a whole section dedicated to this. Instead, we viewed this as mostly out-of-scope, as --version is a feature of helm install. So, instead, we included a note at the end of the step and linked out to helm's docs.
| - **Air-gapped environments** require additional configuration. See [Helm chart air-gapped environment installation](/self-managed/deployment/helm/configure/registry-and-images/air-gapped-installation.md). | ||
| - **Image sources**: By default, the Helm chart uses Bitnami open-source images for infrastructure dependencies (PostgreSQL, Elasticsearch, Keycloak). For production environments, Camunda recommends using Bitnami Premium images for enhanced security and vendor support. For detailed information about image types, CVE handling policies, and installation procedures, see [Install Bitnami enterprise images](/self-managed/deployment/helm/configure/registry-and-images/install-bitnami-enterprise-images.md). | ||
| - **Infrastructure deployment alternatives**: For production deployments, consider using [vendor-supported infrastructure deployment methods](/self-managed/deployment/helm/configure/vendor-supported-infrastructure.md) with official operators for PostgreSQL, Elasticsearch, and Keycloak. | ||
| | Service | URL | |
There was a problem hiding this comment.
Prefer a table for reference information.
|
|
||
| If you would like to further customize the Camunda 8 Self-Managed Helm chart, please proceed to the following section:--> | ||
| - [Configure and install the helm chart in a production environment](/self-managed/deployment/helm/install/production/index.md). | ||
| - [Customize your installation, by modifying the Helm chart configuration](/self-managed/deployment/helm/configure/index.md). |
There was a problem hiding this comment.
Have fewer "next steps", and start them with action verbs as user should "do" something as a next step.
Hackathon project. For discussion only.
Description
The idea was to walk through a guide and a tutorial and apply as much of the feedback provided by the team during the pre-hackathon prep as we could, resulting in progress toward our first content-type exemplars.
For this exercise, we used these two docs:
Due to lack of time, we didn't get through much of "Orchestrate human tasks".
Result
We noticed several applicable emergent patterns, such as:
We also discussed and debated other ideas that resulted in no particular preference: