Clarify URL/address inconsistencies across SaaS, Self-Managed, and Modeler

[christinaausley]

Based on this Slack thread, there are several inconsistencies (or rather, a lack of clarification) surrounding the topics of cluster URL and address.

See this Google Doc for ongoing research and feedback before we move forward with an action plan and PR.

[christinaausley]

Note several comments in this Google Doc for feedback and questions still to answer.

Notably, I met with @melanie-butcher this week to discuss. She is working with her team on sifting through current usage in the strings, so we should have more answers following this mini research project in the best way to move forward, all based on our current usage.

If you feel I should loop in any additional individuals for thoughts, please let me know. We are reaching the tail end of this "research" period, and I'll get to making hard decisions on the terms and launching a PR for any necessary corrections.

[akeller]

What's the status here? Anything left to get this to the finish line?

[christinaausley]

Followed up with @melanie-butcher today to see what her team has uncovered -- will update accordingly this week with any necessary action items to get this across the finish line 👍

[christinaausley]

I haven't heard from @melanie-butcher yet, so I've launched the doc for additional feedback in Slack before moving forward on glossary updates and a PR here.

[melanie-butcher]

@christinaausley - The doc is good. I'm not sure exactly what you are looking for from me?

[christinaausley]

@melanie-butcher Do you have any additional opinions or thoughts based on how the existing strings use these terms?

[christinaausley]

I've updated this document according to my own research and some feedback.

This has been launched across engineering and teams for final feedback, so I can officially launch a PR next week.

[christinaausley]

Feedback noted in Google Doc. Will add to Glossary and PR fixes as appropriate by EOD 8/18.

[christinaausley]

Pushed back as a result of other priorities this week, but will review feedback and make adjustments next week 💯

[christinaausley]

ALRIGHT! After lots of back and forth review, I've decided on the following action items, and terms to add to the glossary for the next update:

• Web address should instead be referred to as URL.
• Ensure endpoint (server connection endpoint) is used appropriately across docs.
• When we include the protocol (grpcs://, for example), this should be referred to as URL.
• When talking about Zeebe endpoints, we should leave this without protocol, and up to the user to include. May add an admonition to note this.
• Rename Zeebe address to ZEEBE_GATEWAY_ADDRESS -- to discuss with @Zelldon as backlog item.
• Use cluster endpoint in API docs where needed. Modeler connecting to the cluster, should use the Cluster URL instead.
• Cluster URL (via grpcs, no http/s with port, http/s with port) only should be referred to as cluster URL.
• Add action item terms to glossary.

Planning to PR these adjustments next week!

[akeller]

Thank you for your perseverance here @christinaausley! I love the collaboration within the doc too. Lots of great input here about what is for what and why 🎉

[christinaausley]

This is PRed and in review -- will wait for some feedback from @Zelldon in the PR, but note these terms will be added to the glossary in the release next week!

[Zelldon]

I gave my input on the PR @christinaausley. Furthermore, I created camunda/camunda#14126

[christinaausley]

Wrapping up one lingering comment and should have this merged in next week, though this has been updated across the glossary 👍