E2E docs experience getting started guides #3988
Conversation
akeller
added
component:docs
|
👋 🤖 🤔 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/.
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. |
| Your preview env has been torn down. |
There was a problem hiding this comment.
I think that this is useful first step towards reorganizing these guides, and don't think it should be held up.
My questions for future iterations are mostly around: what do we expect users to get out of interacting with this section/what, if anything, is the result of "Get started"? Right now this section is very tutorial-heavy. I don't think we have a lot of flow into how-to related sections, or ways for users who don't want a walkthrough tutorial to get to the how-to guide content they might prefer/need.
Once we have a better "quickstart" method for SM, I'd like to see that having its own page, possibly with a division between initial setup content (quickstarts, the account sign-up guide), and tutorial-related content (the "by use case" section).
| This tutorial is not intended for production purposes. | ||
| ::: | ||
|
|
||
| In this guide, we'll step through using Spring Boot and the [Spring Zeebe SDK](/apis-tools/spring-zeebe-sdk/getting-started.md) with Desktop Modeler to interact with your local Self-Managed Camunda 8 installation. You can also follow this guide with SaaS and Web Modeler after you [create an account](https://signup.camunda.com/accounts?utm_source=docs.camunda.io&utm_medium=referral). |
There was a problem hiding this comment.
Is it very feasible for a SaaS user to come in and use this tutorial? There's some later references to SM, to the Zeebe config, etc - I think it may need a few more tweaks to fulfill this, which we may want to iterate on later.
For a faster release, it might be helpful to have a note here for users who have ended up in the wrong place. "Looking to get started with Camunda SaaS? [Link to the model-your-first-process guide.] Quickly let anyone who's landed here that doesn't want a Java- or SM-heavy experience find their way back out.
There was a problem hiding this comment.
I'm getting mixed feedback on this exact topic. If our goal is to enable SM users better but not alienate SaaS users, what I have in the PR is a compromise of sorts. We could change the wording a bit to say you can do something similar in SaaS and Web Modeler, but you won't find the exact guidance here.
There was a problem hiding this comment.
@christinaausley since you are online for a bit today, do you have thoughts here you want to add?
There was a problem hiding this comment.
Is it very feasible for a SaaS user to come in and use this tutorial? There's some later references to SM, to the Zeebe config, etc - I think it may need a few more tweaks to fulfill this, which we may want to iterate on later.
I've launched an issue for a second iteration of this particular guide based on feedback pulled in from @crobbins215, so if we want to move quickly on this PR, I would feed this feedback (pun unintended) into that issue.
In fact, the Step 1 suggested improvement based on the feedback is to add a hint with a link to SaaS as an alternative installation method.
There was a problem hiding this comment.
We could change the wording a bit to say you can do something similar in SaaS and Web Modeler, but you won't find the exact guidance here.
So, I think all of this to say that if we want to make a quick change here, this would be the solution.
There was a problem hiding this comment.
Added
While this guide focuses on Self-Managed, you can do something similar with SaaS.
We also still have the banner with a link to SaaS.
|
|
||
| This guide will walk you through working with a REST Connector task as a first time Camunda 8 user. The REST Connector is a [protocol Connector](/components/connectors/out-of-the-box-connectors/available-connectors-overview.md#protocol-connectors), where you can make a request to a REST API and use the response in the next steps of your process. | ||
|
|
||
| :::note | ||
| New to Connectors? Review our [introduction to Connectors](/components/connectors/introduction.md) to get familiar with their capabilities, and have a closer look at all of the available [out-of-the-box Connectors](/components/connectors/out-of-the-box-connectors/available-connectors-overview.md). | ||
| ::: | ||
|
|
||
| <Tabs> |
There was a problem hiding this comment.
Love this tabbed approach idea. I do think both of these would still be valuable as one-page guides (especially because we can add tabs to the developer guide as we iron out alternate methods of getting set up), but having the reminders here works for this iteration.
There was a problem hiding this comment.
@conceptualshark, where would you place these one-page guides in the sidebar structure of this PR?
There was a problem hiding this comment.
Within the context of these changes, I'd considered something like:
Get started
- With Camunda Self-Managed
-- The java install info
-- the Spring guide
- With Camunda SaaS
-- The account guide
-- Model your first process
- By use case
-- the existing use case docs
In a future iteration, something like this could naturally build out a more directed, result-oriented experience for the initial SaaS vs Self-Managed steps (where the setup is different, and then those personas might want/need slightly different initial onboarding experiences). We could then have more directed "Next steps" - other guides we commonly see those personas needing to head to next, which could be more unified/install agnostic use guides.
There was a problem hiding this comment.
Great start! I really like it.
I think there is one key bug: the "Get started with MS" (REST Connector) example will not work out of the box in SM because Connectors runtime is not running, and Connectors are not injected into desktop modeler per default (at the moment).
- How to inject connector templates into desktop modeler is not really well documented. The technical concepts are explained here, but there is no real link to the connector templates
- How to run the connector runtime is only briefly touched here (but via HELM). AFAIK we do not explain how to start connector runtime in a SM environment without HELM anywhere (correct me if wrong).
=> Isn't this a fundamental flaw in our Connectors SM Install documentation? Maybe it would make sense if the Connectors team documents how to install connectors in SM without HELM and Web Modeler, and then you can link to that?
==> Until we have this, I ask myself whether the MS orchestration guide should be only geared towards SaaS.
The bug highlighted makes me wonder, whether we should have someone (could be a DevEx Engineer, or a QA) follow through all of these guides, to ensure they work e2e.
|
@MaxTru I'm struggling with your feedback - the Connectors runtime and injecting Connectors into Desktop Modeler would impact the "Get Started with API Orchestration" guide, right? Not "Get Started with Microservice Orchestration"? Or both?
Yes, 100%. To keep this iterative, I can remove the SM steps in the Get Started with API Orchestration guide for now. And 10000% I would love to get a culture of testing the guides. We have significantly reduced capacity in DevEx until after the retreat. I'm still having issues running the plain java install on my own machine, but I have time set aside to try again. |
Co-authored-by: Cole Isaac <82131455+conceptualshark@users.noreply.github.com>
You are right - it is about "Get started with API Orchestration". Sorry! |
Can you surface this with Connectors (EM, and PMs)? I can also support if that helps you. |
| @@ -1,15 +1,22 @@ | |||
| --- | |||
| id: getting-started-java-spring | |||
| title: Getting started as a Java developer using Spring | |||
| sidebar_label: Getting started as a Java developer using Spring | |||
| title: Get started as a Java developer using Spring | |||
There was a problem hiding this comment.
I'll have another look at these naming conventions in https://github.com/camunda/developer-experience/issues/253.
stylistic clean up
stylistic clean up
Description
For scope and updates, see https://camunda.slack.com/archives/C077J92G8LX.
When should this change go live?
holdlabel or convert to draft PR)PR Checklist
/versioned_docsdirectory./docsdirectory (aka/next/).