Plausibility check of new Optimize 7 docs

[mboskamp]

Acceptance Criteria (Required on creation)

• Skim through the changes/additions that were migrated to the Optimize 7 docs in this ticket and flag anything incorrect or worth changing.
• Skim through the published docs and flag if you find anything that is missing and noteworthy to move as well.

Hints

The following branches have been updated:

• latest (same content as 3.14)
• 3.14 (same content as master/latest)
• 3.13
• 3.12
• 3.11

Links

Breakdown

Pull Requests

Preview Give feedback

No tasks being tracked yet.

[mboskamp]

Hey @PHWaechtler, do you mind checking the content I migrated for the docs for any inconsistencies?

You can find out what was migrated from this ticket.
I released 3.14 as latest and develop, so the content there is identical.
3.11-3.13 should only have the documentation for things that were added for those versions. Again, see the above ticket for what was added.

Please also take a look at the most important parts (supported environments, configuration properties, update guides). The base version I used was 3.8. Then I migrated the content from the respective version branch from docs.camunda.io. There might be stuff that I missed.

[PHWaechtler]

Hi @mboskamp ,
solid chunk of docs here 🚀 I looked through the changes and did my best to collect everything I've noticed. Its possible I've overlooked things, but I guess we can always update things later as well in that case. Here are my notes, not all of them are important to change right now, some we could also open follow up tickets for:

Migration & upgrade instructions:
- the "update from" column in the table only contains 3.7.3 OpenSearch and 3.7.x OpenSearch - lets also add a row for other users not on 3.7 opensearch
- section 5 is incorrectly listed as a subsection of section 4 (visible in the right hand side menu). Lets fix this
- is it possible to link to section 5 directly from the table?
- Section 5 contains a link to section 3.1 but its not working properly
- This is not a big deal, but for some reason when I click on the very last item (the reimport section) in the menu on the right, while it does take me there it highlights section 6 making it look as if I'm on the previous section
- This is a nitpick and may have already been like that before, but can we revert the menu order for the update notes to have the most recent version at the top and the oldest version at the bottom?

Dashboards
I thnk we're missing info about the "dashboards maintained by camunda":
- https://docs.camunda.io/optimize/3.13.0/components/userguide/process-dashboards/
- https://docs.camunda.io/optimize/3.13.0/components/userguide/instant-process-dashboards/
Edit: I see now that this was listed as ignored, was there a reason for that? Or will we add it later

KPI:
I think were missing the KPI page: https://docs.camunda.io/optimize/3.13.0/components/userguide/process-KPIs/

This addition that’s listed as ignored I think we can also migrate, it adds more clarification: camunda/camunda-docs@8872f99

Backup:
The backup docs still only mention elasticsearch (instead of "database"), lets check with the opensearch team whether that API is already available in opensearch. If it is available, lets alter the docs to say "database" instead of "elasticsearch". If it is not available in OS, lets add a notice about that in the docs

General opensearch terminology:
There are still a few places where we only refer to Elasticsearch instead of saying "database" (for example in the Footer page: https://docs.camunda.org/optimize/3.14/user-guide/footer/). I don’t think we need to adjust this right now, but we could consider doing this in a follow up

Object variables
There is this section on zeebe variables that we can remove: https://docs.camunda.org/optimize/3.13/technical-guide/setup/object-variables/#zeebe-object-variables

Third party libraries
https://docs.camunda.org/optimize/latest/technical-guide/third-party-libraries/
I just spot checked a couple random ones and I think this page is not up to date, lets double check these and update.

Telemetry:
We have removed easytelemetry with 3.14.0-alpha2 so this documentation can be removed from here and the config page for 3.14

Security instructions:
https://docs.camunda.org/optimize/3.14/technical-guide/setup/security/
On this page, the link to the database section is broken (still says "secure elasticsearch" but the section has been renamed so the link doesn’t work). However, I also noticed that this section was completely removed in C8 and we're now just linking to the config pages and the ES/OS own documentation. I would leave it up to you which adjustment is less effort.

Let me know if you have any questions!
Helene

[mboskamp]

Hey Helene

Thank you for checking the migrated content and your detailed feedback. Super helpful!

Migration & upgrade instructions:

• the "update from" column in the table only contains 3.7.3 OpenSearch and 3.7.x OpenSearch - lets also add a row for other users not on 3.7 opensearch

👍 Agree! This is the correct table: https://docs.camunda.io/optimize/self-managed/optimize-deployment/migration-update/camunda-7/instructions/

• section 5 is incorrectly listed as a subsection of section 4 (visible in the right hand side menu). Lets fix this
• is it possible to link to section 5 directly from the table?
• Section 5 contains a link to section 3.1 but its not working properly

👍 Agree!

• This is not a big deal, but for some reason when I click on the very last item (the reimport section) in the menu on the right, while it does take me there it highlights section 6 making it look as if I'm on the previous section
  The anchor link is correct.

I agree, the browser does not scroll all the way down. But I don't think this is something we can easily fix. I would not spend time to investigate this now.

• This is a nitpick and may have already been like that before, but can we revert the menu order for the update notes to have the most recent version at the top and the oldest version at the bottom?

👍 It makes sense to reverse the order. For Camunda 7 the newest version is the first in the list. However, I would not prioritize this. I will create a follow-up task for it.

Dashboards
I thnk we're missing info about the "dashboards maintained by camunda":

• https://docs.camunda.io/optimize/3.13.0/components/userguide/process-dashboards/
• https://docs.camunda.io/optimize/3.13.0/components/userguide/instant-process-dashboards/
  Edit: I see now that this was listed as ignored, was there a reason for that? Or will we add it later

👍 I think I misunderstood that section. I thought it was only for Optimize 8. I will add the missing pages for 3.13 and 3.14

KPI:
I think were missing the KPI page: https://docs.camunda.io/optimize/3.13.0/components/userguide/process-KPIs/

This addition that’s listed as ignored I think we can also migrate, it adds more clarification: camunda/camunda-docs@8872f99

👍 Agree. Same as above. I will migrate the additional content.

Backup:
The backup docs still only mention elasticsearch (instead of "database"), lets check with the opensearch team whether that API is already available in opensearch. If it is available, lets alter the docs to say "database" instead of "elasticsearch". If it is not available in OS, lets add a notice about that in the docs

👍 Will reach out to the Optimize 8 team to find out if the backup/restore API works with Opensearch.

General opensearch terminology:
There are still a few places where we only refer to Elasticsearch instead of saying "database" (for example in the Footer page: https://docs.camunda.org/optimize/3.14/user-guide/footer/). I don’t think we need to adjust this right now, but we could consider doing this in a follow up

👍 I agree. I will create a follow-up issue.

Object variables
There is this section on zeebe variables that we can remove: https://docs.camunda.org/optimize/3.13/technical-guide/setup/object-variables/#zeebe-object-variables

👍 Sure, this page should be removed.

Third party libraries
https://docs.camunda.org/optimize/latest/technical-guide/third-party-libraries/
I just spot checked a couple random ones and I think this page is not up to date, lets double check these and update.

❓ I checked a few dependencies (frontend and backend) and I believe the pages are up to date for latest/3.14. I compared 3.14 backend and frontend with this page from the C8 docs. Can you point me to the pages that you think are not in sync?

Telemetry:
We have https://github.com/camunda/camunda-optimize/issues/10143 so this documentation can be removed: from here: https://docs.camunda.org/optimize/latest/technical-guide/setup/telemetry/ and the config page for 3.14

👍 Makes sense. I will remove that page for 3.14/latest.

Security instructions:
https://docs.camunda.org/optimize/3.14/technical-guide/setup/security/
On this page, the link to the database section is broken (still says "secure elasticsearch" but the section has been renamed so the link doesn’t work). However, I also noticed that this section was completely removed in C8 and we're now just linking to the config pages and the ES/OS own documentation. I would leave it up to you which adjustment is less effort.

👍 Let's remove the section and point to the Security section of the configuration guide.

I will create a follow-up ticket for the necessary changes and another follow-up for the low-prio/nice-to-have changes.

[mboskamp]

Created #4833 for the necessary changes and #4835 for nice-to-haves.

[mboskamp]

Backup:
The backup docs still only mention elasticsearch (instead of "database"), lets check with the opensearch team whether that API is already available in opensearch. If it is available, lets alter the docs to say "database" instead of "elasticsearch". If it is not available in OS, lets add a notice about that in the docs

👍 Will reach out to the Optimize 8 team to find out if the backup/restore API works with Opensearch.

OpenSearch will support this feature with 3.15. Documentation will be handled with camunda/camunda#23615.

[PHWaechtler]

❓ I checked a few dependencies (frontend and backend) and I believe the pages are up to date for latest/3.14. I compared 3.14 backend and frontend with this page from the C8 docs. Can you point me to the pages that you think are not in sync?

You're right those are in sync. I realise now I made the mistake of comparing the versions from the docs with what we have in the pom on current master but the docs are still for 3.14 obviously 😬