Split element templates docs into C7 and C8

[barmac]

Description

This PR splits the element templates docs into C7 and C8 sections, with C8 being the primary source. The goal is to make the docs easier to read as the reader can focus on the platform they want to support. Read more in the issue linked below:

Closes https://github.com/bpmn-io/internal-docs/issues/663
Closes #1450

When should this change go live?

• This change is not yet live and should not be merged until {ADD_DATE} (apply hold label or convert to draft PR)?
• There is no urgency with this change.
• This change or page is part of a marketing blog, conference talk, or something else on a schedule.
• This functionality is already available but undocumented.
• This is a bug fix or security concern.

PR Checklist

• I have added changes to the relevant /versioned_docs directory, or they are not for an already released version.
• I have added changes to the main /docs directory (aka /next/), or they are not for future versions.
• My changes require an Engineering review, and I've assigned an engineering manager or tech lead as a reviewer, or my changes do not require an Engineering review.
• My changes require a technical writer review, and I've assigned @christinaausley as a reviewer, or my changes do not require a technical writer review.

[barmac]

@CatalinaMoisuc @christian-konrad Looking forward to your feedback :)

[christinaausley]

@akeller Also looping you in here -- do you think it would be best to keep all C7-specific content in the Platform 7 docs? Maybe I'm misunderstanding here, and we should just apply the Platform 7 labels.

[akeller]

@christinaausley We moved all Modeler docs (like Optimize docs) to docs.camunda.io. I like the clear separation here and the focus on C8. This is the right choice.

In the future, if it makes sense to move or remove the C7 content, it will already be separate. For consistency with other C7 only docs, please add the label/badging.

Note - I did not review the content in this PR. If you are looking for a content review, please add me as a reviewer, and I'll come back.

[christinaausley]

Technical review in latest commit 👍

[CatalinaMoisuc]

@barmac @christian-konrad @sbuettner question for all of you:

Do you see any reason why we should have the C7 documentation here and not in https://docs.camunda.org/manual/7.19/modeler/element-templates/?

[barmac]

@barmac @christian-konrad @sbuettner question for all of you:

Do you see any reason why we should have the C7 documentation here and not in https://docs.camunda.org/manual/7.19/modeler/element-templates/?

Please read Amara's comment above: #2369 (comment)

Personally, I could live with both docs.camunda.io as single source of Modeler docs, and separate C7 and C8. However, as we have already moved Element Templates docs to docs.camunda.io before this PR, I'd rather not invest time in migrating them back to the legacy docs.

[sbuettner]

I am with @CatalinaMoisuc here as we should try to split and not mix c7 & c8 content here but I can understand @barmac as well. No hard feelings. I think @akeller is right and we should try to phase out c7 content in the new docs eventually.

[CatalinaMoisuc]

This additional sentence that exists on the C7 page might also be useful here:
"Element templates are currently available in BPMN diagrams only.".

[CatalinaMoisuc]

@barmac I suggest that some other Engineer from the core team cross-checks the differences between C7 and C8.

[barmac]

OK

[CatalinaMoisuc]

Same as above @barmac let's have another Engineer from the core team review the technical differences between C7 and C8 templates.

[philippfromme]

I can't find the binding type bpmn:Message#property documented anywhere. Are we aware of that?

[barmac]

Hmm I believe I overlooked this when I implemented the feature 🤡

[barmac]

Will be done via https://github.com/bpmn-io/internal-docs/issues/797

[philippfromme]

I think we forgot about bpmn:Message#zeebe:subscription#property here (cf. https://github.com/bpmn-io/bpmn-js-element-templates/blob/main/src/cloud-element-templates/create/MessageZeebeSubscriptionBindingProvider.js#L39).

[barmac]

Cf. #2369 (comment)

[akeller]

@christinaausley, do we have anything in the style guide on "the modeler" vs. "Modeler"? We use both in this PR (and likely in the rest of the element template docs).

@barmac, for the content here (in this PR), this is only in the scope of Desktop Modeler? Or does some content also apply to Web Modeler? It's currently nested in Desktop Modeler, but if it applies to both modeling experiences, we should move it.

We should add badging to Camunda Platform 7 pages -
<span class="badge badge--platform">Camunda Platform 7 only</span>.

I would even recommend to be more overt about the title of the pages - "Using templates in Camunda Platform 7" - but keeping them short in the sidebar. This way users have the most visual context between the sidebar, URL, page title, and breadcrumbs.

We need to be careful about duplicate content here, where Google chooses what page it wants to rank (not ideal). The two configuring-templates.md are nearly identical. Changing the title on the Camunda Platform 7 page will help, but we should also change the metadata description. In the near future, do we see significant divergence in the content on these pages?

[barmac]

Hi Amara, thanks for looking into this.

@barmac, for the content here (in this PR), this is only in the scope of Desktop Modeler? Or does some content also apply to Web Modeler? It's currently nested in Desktop Modeler, but if it applies to both modeling experiences, we should move it.

The C7 part is for Desktop Modeler only. From the C8 part, "Defining templates" and others can be applied to both while "Configuring templates" is Desktop Modeler only.

We should add badging to Camunda Platform 7 pages -
<span class="badge badge--platform">Camunda Platform 7 only</span>.

I will do this.

I would even recommend to be more overt about the title of the pages - "Using templates in Camunda Platform 7" - but keeping them short in the sidebar. This way users have the most visual context between the sidebar, URL, page title, and breadcrumbs.

Great idea. I will apply the titles.

We need to be careful about duplicate content here, where Google chooses what page it wants to rank (not ideal). The two configuring-templates.md are nearly identical. Changing the title on the Camunda Platform 7 page will help, but we should also change the metadata description. In the near future, do we see significant divergence in the content on these pages?

Perhaps we could link from C7 part to C8 as canonical? WDYT?

[akeller]

Perhaps we could link from C7 part to C8 as canonical? WDYT?

@pepopowitz this is related to the last item in #1143. Can we (easily) specify canonicals at all right now?

☝️ If no - @barmac, I'll monitor this with our SEO tools. AFAIK there are no negative consequences of duplicate content, just a potential lack of control with ranking. No action required for this.

[CatalinaMoisuc]

cc @christian-konrad.

[nikku]

I have a couple of thoughts on this PR:

• What is really different is the defining-templates page. I propose to only change that page, and keep the other pages agnostic of C7 and C8. This helps us to keep things maintainable.

• As we discussed once in a while we also mix up app documentation ("configuring templates") and element template documentation ("defining templates", "about templates") here. We may want to consider to split these appart. ➡️ Element templates are, in different versions, supported across web and desktop, and hence shall be featured on the same level as Camunda Forms (one level up).

• I'd personally de-emphasize Camunda 7, i.e. by introducing a Define Templates sub-folder with a landing page + a dedicated Legacy (Camunda 7) page:

  Element Templates
    Define Templates
    Camunda 7 (or Legacy)
      Define Templates
  

• Even better, to avoid confusion, we could move Camunda 7 content to a dedicated Camunda Desktop Modeler -> Camunda 7 -> Element Templates -> ... section. Once that content is farther away both users and SEO will be confused less.

[pepopowitz]

Perhaps we could link from C7 part to C8 as canonical? WDYT?

@pepopowitz this is related to the last item in #1143. Can we (easily) specify canonicals at all right now?

☝️ If no - @barmac, I'll monitor this with our SEO tools. AFAIK there are no negative consequences of duplicate content, just a potential lack of control with ranking. No action required for this.

Unless docusaurus has fixed something in the last couple versions, I don't think there is an easy way to specify a canonical on an individual page. (See the notes I just added in #1143 (comment).)

[christinaausley]

@CatalinaMoisuc and I discussed a few things on a call this morning:

• We can always iterate moving forward, though I would recommend sharing the changes in the Forum/Jira for additional feedback after this is live regardless.

• If we are increasingly worried about distinguishing between C7/C8, we can always add a note as shown in a document like this.

Even better, to avoid confusion, we could move Camunda 7 content to a dedicated Camunda Desktop Modeler -> Camunda 7 -> Element Templates -> ... section. Once that content is farther away both users and SEO will be confused less.

This works for me, but that is several nested levels. Perhaps keeping things split up as easily as possible is a good place to start, and if there is still confusion we can always go a level deeper.

@akeller do we have anything in the style guide on "the modeler" vs. "Modeler"? We use both in this PR (and likely in the rest of the element template docs).

We do clearly define the product in the WCoE as "using Web Modeler/Desktop Modeler" as opposed to "the Web Modeler", but I don't think we've defined "modeler yet".

If we are referring to Web Modeler/Desktop Modeler specifically, it should be documented as such. If we are referring to some external modeler, using "your modeler" is fine (though we should likely only be referring to our own product regardless, yeah?)

[barmac]

I just noticed that I missed to update the versioned docs. This is done via 6b47210

[christinaausley]

@barmac How can I continue to support you with this? Looking for any additional review? Anywhere I can assist?

[barmac]

I've restructured the docs according to @akeller's comment.

Since I am on vacation from today on, please feel free to make any adjustments, and I am looking forward to merging this :)

Thank you @christinaausley @akeller @nikku @CatalinaMoisuc @philippfromme for support in making this contribution substantially better!

[akeller]

Thank you for your patience and flexibility here @barmac! Enjoy your vacation 🏖️

[nikku]

Let's merge this. Thanks all.